nugap 0.1.0__py3-none-any.whl

nugap/__init__.py

@@ -0,0 +1,29 @@
+"""nugap: the Vinnicombe nu-gap metric and a pipeline for comparing
+time-course data across two conditions.
+
+Quick start
+-----------
+    from nugap import tf, nu_gap
+    d = nu_gap(tf([1],[1,1]), tf([1],[1,1.2]))   # ~0.07
+
+    from nugap import compare_conditions
+    df = compare_conditions(data_A, data_B, t)   # ranked table of changes
+"""
+
+from .systems import LTI, tf, from_zpk, from_control, to_continuous
+from .metric import nu_gap, chordal_distance, winding_condition
+from .fitting import fit_model, fit_prony, fit_arx, fit_arx_fast, fit_first_order, FitResult
+from .pipeline import compare_conditions, compare_variable
+from .replicates import compare_conditions_replicates, compare_variable_replicates
+from .network import compare_network
+
+__all__ = [
+    "LTI", "tf", "from_zpk", "from_control", "to_continuous",
+    "nu_gap", "chordal_distance", "winding_condition",
+    "fit_model", "fit_prony", "fit_arx", "fit_arx_fast", "fit_first_order", "FitResult",
+    "compare_conditions", "compare_variable",
+    "compare_conditions_replicates", "compare_variable_replicates",
+    "compare_network",
+]
+
+__version__ = "0.1.0"

nugap/fitting.py

@@ -0,0 +1,267 @@
+"""Fit discrete-time LTI models to time-course data.
+
+This is the part of the pipeline that turns a measured trajectory into an
+``LTI`` system that the nu-gap metric can compare. It is deliberately
+separated from the metric so you can swap in your own identification routine
+(e.g. to mirror exactly what MATLAB's System Identification Toolbox did).
+
+Two cases are handled:
+
+* **Input/output data** (you applied a known stimulus ``u`` and recorded the
+  response ``y``): an ARX model is fitted by linear least squares, giving a
+  discrete transfer function B(z)/A(z).
+
+* **Output-only data** (you only have the response ``y``, e.g. a signal that
+  rises and relaxes after a perturbation): Prony's method fits ``y`` as the
+  impulse response of a discrete LTI system, recovering its poles (modes) and
+  a numerator.
+
+Sampled data -> discrete-time models is the natural and numerically clean
+choice; the nu-gap metric evaluates these on the unit circle.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import numpy as np
+
+from .systems import LTI
+
+
+@dataclass
+class FitResult:
+    model: LTI
+    order: int
+    r2: float          # fit quality of the simulated/predicted output
+    method: str
+    sample_time: float
+
+
+def _sample_time(t) -> float:
+    t = np.asarray(t, dtype=float)
+    dts = np.diff(t)
+    dt = float(np.median(dts))
+    if dt <= 0:
+        raise ValueError("time vector must be increasing")
+    return dt
+
+
+def _simulate(num, den, u, y0len):
+    """Simulate a discrete tf B/A driven by u (impulse if u is None)."""
+    import warnings
+    from scipy.signal import dlsim, TransferFunction, BadCoefficients
+
+    if u is None:
+        u = np.zeros(y0len)
+        u[0] = 1.0
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", BadCoefficients)
+        sysd = TransferFunction(num, den, dt=1.0)
+        _, yout = dlsim(sysd, u)
+    return np.asarray(yout).ravel()
+
+
+def _r2(y, yhat):
+    y = np.asarray(y, dtype=float)
+    n = min(len(y), len(yhat))
+    y, yhat = y[:n], yhat[:n]
+    ss_res = np.sum((y - yhat) ** 2)
+    ss_tot = np.sum((y - np.mean(y)) ** 2)
+    return float(1.0 - ss_res / ss_tot) if ss_tot > 0 else 0.0
+
+
+def fit_prony(t, y, order: int):
+    """Fit y as the impulse response of a discrete LTI of given order.
+
+    Returns (num, den) discrete polynomial coefficients (highest power first).
+    """
+    y = np.asarray(y, dtype=float).ravel()
+    N = len(y)
+    na = order
+    if N <= 2 * na:
+        raise ValueError("not enough samples for the requested order")
+
+    # Linear prediction: y[k] = -sum_{j=1..na} a_j y[k-j]
+    rows = []
+    rhs = []
+    for k in range(na, N):
+        rows.append([-y[k - j] for j in range(1, na + 1)])
+        rhs.append(y[k])
+    A = np.asarray(rows)
+    b = np.asarray(rhs)
+    a, *_ = np.linalg.lstsq(A, b, rcond=None)
+    den = np.concatenate([[1.0], a])  # [1, a1, ..., a_na]
+
+    # Numerator from the convolution relation treating y as impulse response.
+    nb = na
+    num = np.zeros(nb + 1)
+    for k in range(nb + 1):
+        s = 0.0
+        for j in range(k + 1):
+            if j < len(den):
+                s += den[j] * y[k - j]
+        num[k] = s
+    return num, den
+
+
+def fit_arx(t, y, u, na: int, nb: int | None = None, nk: int = 1):
+    """Fit an ARX model A(z) y = B(z) u by least squares.
+
+    Returns (num, den) of the discrete transfer function B(z)/A(z).
+    """
+    y = np.asarray(y, dtype=float).ravel()
+    u = np.asarray(u, dtype=float).ravel()
+    N = len(y)
+    if nb is None:
+        nb = na
+    start = max(na, nb + nk)
+    rows, rhs = [], []
+    for k in range(start, N):
+        row = [-y[k - j] for j in range(1, na + 1)]
+        row += [u[k - nk - i] for i in range(0, nb + 1)]
+        rows.append(row)
+        rhs.append(y[k])
+    M = np.asarray(rows)
+    b = np.asarray(rhs)
+    theta, *_ = np.linalg.lstsq(M, b, rcond=None)
+    a = theta[:na]
+    bb = theta[na:]
+    den = np.concatenate([[1.0], a])
+    num = np.concatenate([np.zeros(nk), bb])  # account for input delay
+    return num, den
+
+
+def _cap_orders(orders, N: int):
+    """Limit candidate orders so we never overfit short trajectories.
+
+    A model of order p has ~2p+1 free parameters; with N samples we keep
+    roughly 5 samples per parameter, so p_max ~ N//5 (at least 1).
+    """
+    p_max = max(1, N // 5)
+    capped = [o for o in orders if o <= p_max]
+    return capped or [1]
+
+
+def fit_arx_fast(t, y, u, na: int, nb: int = 0, nk: int = 1, dt=None):
+    """Fast ARX fit of arbitrary order with a recursive simulation R^2.
+
+    Fits A(z) y = B(z) u with ``na`` poles, ``nb+1`` numerator taps and input
+    delay ``nk`` by linear least squares, then simulates the model from u
+    (warm-started on the first samples) to score the fit. Returns (LTI, r2).
+
+    Designed to be called millions of times for pairwise identification, so it
+    avoids scipy per call. ``na=1, nb=0`` reproduces the first-order model
+    K/(tau s + 1) (MATLAB ``tfest(data, 1, 0)``); ``na=2, nb=0`` is the
+    canonical two-pole, no-zero second-order system.
+    """
+    y = np.asarray(y, dtype=float).ravel()
+    u = np.asarray(u, dtype=float).ravel()
+    if dt is None:
+        dt = _sample_time(t)
+    na, nb, nk = int(na), int(nb), int(nk)
+    N = len(y)
+    start = max(na, nb + nk)
+    n_params = na + nb + 1
+    if N - start < n_params:
+        raise ValueError(
+            f"not enough samples ({N}) for order na={na}, nb={nb}")
+
+    rows, rhs = [], []
+    for k in range(start, N):
+        row = [-y[k - i] for i in range(1, na + 1)]
+        row += [u[k - nk - i] for i in range(0, nb + 1)]
+        rows.append(row)
+        rhs.append(y[k])
+    theta, *_ = np.linalg.lstsq(np.asarray(rows), np.asarray(rhs), rcond=None)
+    a = theta[:na]
+    b = theta[na:]
+
+    den = np.concatenate([[1.0], a])
+    num = np.concatenate([np.zeros(nk), b])  # input delay
+
+    # simulate the model from u, warm-started with measured y on [0, start)
+    yhat = np.empty(N)
+    yhat[:start] = y[:start]
+    for k in range(start, N):
+        val = 0.0
+        for i in range(1, na + 1):
+            val -= a[i - 1] * yhat[k - i]
+        for i in range(0, nb + 1):
+            val += b[i] * u[k - nk - i]
+        yhat[k] = val
+
+    ys, yh = y[start:], yhat[start:]
+    ss_tot = np.sum((ys - np.mean(ys)) ** 2)
+    r2 = float(1.0 - np.sum((ys - yh) ** 2) / ss_tot) if ss_tot > 0 else 0.0
+    return LTI(num, den, dt=dt), r2
+
+
+def fit_first_order(t, y, u, dt=None):
+    """First-order ARX fit (one pole, no zero). Thin wrapper around
+    ``fit_arx_fast`` with na=1, nb=0, nk=1. Returns (LTI, r2)."""
+    return fit_arx_fast(t, y, u, na=1, nb=0, nk=1, dt=dt)
+
+
+def fit_model(
+    t,
+    y,
+    u=None,
+    orders=range(1, 5),
+    method: str = "auto",
+) -> FitResult:
+    """Fit a discrete LTI model, selecting the order by AIC.
+
+    Parameters
+    ----------
+    t : array     time stamps (used only to get the sample time)
+    y : array     measured response
+    u : array or None   stimulus, if known
+    orders : iterable of int   candidate model orders to try. Automatically
+        capped to ~N//5 so short trajectories are not overfitted.
+    method : 'auto' | 'prony' | 'arx'
+        'auto' uses ARX when u is given, Prony otherwise.
+
+    Returns
+    -------
+    FitResult
+    """
+    y = np.asarray(y, dtype=float).ravel()
+    dt = _sample_time(t)
+    N = len(y)
+    orders = _cap_orders(list(orders), N)
+
+    if method == "auto":
+        method = "arx" if u is not None else "prony"
+
+    best = None
+    for order in orders:
+        try:
+            if method == "prony":
+                num, den = fit_prony(t, y, order)
+                yhat = _simulate(num, den, None, N)
+                nparams = 2 * order + 1
+            elif method == "arx":
+                num, den = fit_arx(t, y, u, na=order)
+                yhat = _simulate(num, den, np.asarray(u, float).ravel(), N)
+                nparams = 2 * order + 1
+            else:
+                raise ValueError(f"unknown method {method!r}")
+        except Exception:
+            continue
+
+        n = min(len(y), len(yhat))
+        sse = np.sum((y[:n] - yhat[:n]) ** 2)
+        if sse <= 0 or not np.isfinite(sse):
+            continue
+        aic = N * np.log(sse / N) + 2 * nparams
+        r2 = _r2(y, yhat)
+        cand = (aic, order, num, den, r2)
+        if best is None or aic < best[0]:
+            best = cand
+
+    if best is None:
+        raise RuntimeError("model fitting failed for all candidate orders")
+
+    _, order, num, den, r2 = best
+    model = LTI(num, den, dt=dt)
+    return FitResult(model=model, order=order, r2=r2, method=method, sample_time=dt)

nugap/metric.py

@@ -0,0 +1,179 @@
+"""The Vinnicombe nu-gap metric for SISO systems.
+
+Reference: G. Vinnicombe, "Frequency domain uncertainty and the graph
+topology", IEEE Trans. Automatic Control 38 (1993) 1371-1383, and
+G. Vinnicombe, "Uncertain Systems and Feedback" (2001).
+
+For two systems P1, P2 the nu-gap is
+
+    delta_nu(P1, P2) = sup_w  kappa(P1, P2)(w)        if the winding-number
+                                                        condition holds,
+                     = 1                               otherwise,
+
+where the *chordal distance* between two scalar transfer functions at a
+frequency point is
+
+                       |P1 - P2|
+    kappa = ------------------------------------ ,   in [0, 1].
+            sqrt(1+|P1|^2) * sqrt(1+|P2|^2)
+
+The winding-number condition (SISO) is
+
+    wno( 1 + conj(P2) * P1 )  +  eta(P1) - eta(P2) - eta0(P2)  =  0
+
+with eta = number of unstable poles and eta0 = number of boundary poles
+(imaginary axis for continuous systems, unit circle for discrete). If the
+condition fails the systems are "topologically far" and delta_nu = 1.
+
+The result is symmetric: delta_nu(P1, P2) == delta_nu(P2, P1), and lies in
+[0, 1]. 0 means identical dynamics; near 1 means very different.
+"""
+
+from __future__ import annotations
+
+import warnings
+import numpy as np
+
+from .systems import LTI
+
+
+def chordal_distance(P1: np.ndarray, P2: np.ndarray) -> np.ndarray:
+    """Point-wise chordal distance between two frequency responses."""
+    P1 = np.asarray(P1)
+    P2 = np.asarray(P2)
+    return np.abs(P1 - P2) / (np.sqrt(1.0 + np.abs(P1) ** 2) * np.sqrt(1.0 + np.abs(P2) ** 2))
+
+
+def _contour(sys1: LTI, sys2: LTI, n: int):
+    """Build the integration contour and the matching complex points.
+
+    Returns (param, points, closed) where ``points`` are the complex
+    arguments at which to evaluate the transfer functions.
+
+    Continuous: a dense, symmetric grid of frequencies covering the system
+    dynamics by several decades; points = j*w.
+    Discrete: theta in (-pi, pi]; points = exp(j*theta).
+    """
+    if sys1.is_discrete() or sys2.is_discrete():
+        # unit circle
+        theta = np.linspace(-np.pi, np.pi, n, endpoint=True)
+        return theta, np.exp(1j * theta), True
+    # continuous: choose range from the pole/zero magnitudes
+    feats = np.concatenate([
+        np.abs(sys1.poles), np.abs(sys2.poles),
+        np.abs(sys1.zeros), np.abs(sys2.zeros),
+    ])
+    feats = feats[feats > 0]
+    if feats.size:
+        lo = np.log10(feats.min()) - 3
+        hi = np.log10(feats.max()) + 3
+    else:
+        lo, hi = -3.0, 3.0
+    w_pos = np.logspace(lo, hi, n // 2)
+    w = np.concatenate([-w_pos[::-1], w_pos])
+    return w, 1j * w, False
+
+
+def _winding_number(g_vals: np.ndarray, closed: bool) -> int:
+    """Net counter-clockwise encirclements of the origin by g along the
+    contour, from the sampled values g_vals (ordered along the contour).
+
+    For the discrete unit circle the contour is already closed. For the
+    continuous imaginary axis we sweep a very wide symmetric frequency band;
+    because here g(+/-inf) -> a real positive constant, the semicircle at
+    infinity adds no net phase, so the imaginary-axis sweep suffices.
+    """
+    ang = np.unwrap(np.angle(g_vals))
+    total = ang[-1] - ang[0]
+    return int(np.round(total / (2.0 * np.pi)))
+
+
+def _g_on_contour(sys1: LTI, sys2: LTI, points: np.ndarray) -> np.ndarray:
+    """g = 1 + conj(P2) * P1 evaluated on the contour.
+
+    On the imaginary axis / unit circle the para-conjugate P2~ equals the
+    complex conjugate of P2, so this is exactly Vinnicombe's g restricted to
+    the contour.
+    """
+    P1 = sys1.freqresp(points)
+    P2 = sys2.freqresp(points)
+    return 1.0 + np.conjugate(P2) * P1
+
+
+def winding_condition(sys1: LTI, sys2: LTI, n: int = 8192, tol: float = 1e-7):
+    """Evaluate the integer winding-number condition.
+
+    Returns (ok: bool, value: int, touches_origin: bool).
+    """
+    _, points, closed = _contour(sys1, sys2, n)
+    g = _g_on_contour(sys1, sys2, points)
+
+    # If g touches the origin on the contour, the chordal distance reaches 1
+    # somewhere and the systems sit on the boundary -> treat as far.
+    touches = bool(np.min(np.abs(g)) < 1e-9 * max(1.0, np.max(np.abs(g))))
+
+    wno_ccw = _winding_number(g, closed)
+    # Vinnicombe's condition counts clockwise encirclements of the origin
+    # along the Nyquist contour; _winding_number returns the (mathematically
+    # standard) counter-clockwise count, so negate.
+    wno = -wno_ccw
+    eta1, _ = sys1.pole_counts(tol)
+    eta2, eta02 = sys2.pole_counts(tol)
+    value = wno + eta1 - eta2 - eta02
+    ok = (value == 0) and not touches
+    return ok, value, touches
+
+
+def nu_gap(
+    sys1: LTI,
+    sys2: LTI,
+    n: int = 8192,
+    tol: float = 1e-7,
+    return_details: bool = False,
+):
+    """Vinnicombe nu-gap metric delta_nu(sys1, sys2) in [0, 1].
+
+    Parameters
+    ----------
+    sys1, sys2 : LTI
+        SISO systems. Must both be continuous or both discrete with the
+        same sampling time.
+    n : int
+        Number of contour samples (resolution of the frequency sweep).
+    tol : float
+        Tolerance used to classify poles as unstable / on the boundary.
+    return_details : bool
+        If True, also return a dict with the sup-chordal distance, the
+        winding condition value, and the frequency of the maximum.
+
+    Returns
+    -------
+    float  (or (float, dict) if return_details)
+    """
+    if sys1.is_discrete() != sys2.is_discrete():
+        raise ValueError("cannot compare a continuous system with a discrete one")
+    if sys1.is_discrete() and sys2.is_discrete() and sys1.dt != sys2.dt:
+        warnings.warn("comparing discrete systems with different sample times")
+
+    param, points, closed = _contour(sys1, sys2, n)
+    P1 = sys1.freqresp(points)
+    P2 = sys2.freqresp(points)
+
+    kappa = chordal_distance(P1, P2)
+    imax = int(np.nanargmax(kappa))
+    sup_kappa = float(kappa[imax])
+
+    ok, value, touches = winding_condition(sys1, sys2, n=n, tol=tol)
+    delta = sup_kappa if ok else 1.0
+
+    if return_details:
+        details = {
+            "sup_chordal": sup_kappa,
+            "winding_value": value,
+            "winding_ok": ok,
+            "touches_origin": touches,
+            "arg_at_max": float(param[imax]),
+            "result": delta,
+        }
+        return delta, details
+    return delta

nugap/network.py

@@ -0,0 +1,222 @@
+"""Pairwise dynamic-network comparison.
+
+Workflow: within each condition, treat every variable as a candidate input for
+every other variable and fit a first-order input->output model. Then, for each
+ordered pair (i -> j), use the nu-gap to compare the condition-A model with the
+condition-B model. Edges with a large nu-gap are interactions whose dynamics
+changed between conditions.
+
+With replicates, the within-condition nu-gap (replicate vs replicate of the
+same condition) gives a per-edge noise floor; pooled across all edges it forms
+a well-estimated null for FDR-controlled discovery across the millions of
+edges.
+
+Scale note: N variables -> N*(N-1) ordered edges. Each fit is a trivial
+2-parameter least squares; the cost is the metric. First-order systems are
+smooth on the unit circle, so a small ``n`` (default 256) is accurate and keeps
+this tractable. For thousands of variables, run edge batches in parallel
+(the per-edge work is independent) and/or prescreen edges.
+"""
+
+from __future__ import annotations
+
+import itertools
+import numpy as np
+import pandas as pd
+
+from .fitting import fit_arx_fast, _sample_time
+from .metric import nu_gap
+from .replicates import _bh_fdr
+
+
+def _center(arr):
+    """Subtract each replicate's mean (these models assume no offset)."""
+    arr = np.asarray(arr, dtype=float)
+    if arr.ndim == 1:
+        return arr - np.mean(arr)
+    return arr - arr.mean(axis=1, keepdims=True)
+
+
+def _edge_models(reps_in, reps_out, t, dt, na, nb):
+    """Fit a model per replicate for one (input->output) edge."""
+    models, r2s = [], []
+    for u, y in zip(reps_in, reps_out):
+        try:
+            m, r2 = fit_arx_fast(t, y, u, na=na, nb=nb, nk=1, dt=dt)
+            if not m.is_stable() and np.max(np.abs(m.poles)) > 5:
+                continue  # discard wildly diverging fits
+            models.append(m)
+            r2s.append(r2)
+        except Exception:
+            continue
+    return models, r2s
+
+
+def _gap_pairs(models, n):
+    R = len(models)
+    g = {}
+    for i, j in itertools.combinations(range(R), 2):
+        g[(i, j)] = nu_gap(models[i], models[j], n=n)
+    return g
+
+
+def compare_network(
+    data_A: dict,
+    data_B: dict,
+    t,
+    order: int = 1,
+    n_zeros: int | None = None,
+    n: int = 256,
+    center: bool = True,
+    min_r2: float | None = 0.5,
+    gate: str = "either",
+    null_from_reliable_only: bool = True,
+    include_pairs=None,
+    global_null: bool = True,
+    progress: bool = False,
+):
+    """Compare the pairwise interaction network across conditions.
+
+    Parameters
+    ----------
+    data_A, data_B : dict[str, array]
+        variable name -> trajectories. Either 1D (single record) or 2D
+        (n_replicates x n_timepoints). With replicates a per-edge noise floor
+        is computed.
+    t : array
+        Common time vector.
+    order : int
+        Number of poles of the per-edge model. 1 = first-order K/(tau s + 1)
+        (default), 2 = second-order. Needs more time points at higher order.
+    n_zeros : int or None
+        Number of zeros in the numerator. Default None -> 0 (all-pole model:
+        first-order = 1 pole/0 zeros, second-order = 2 poles/0 zeros). Set to 1
+        for e.g. a two-pole/one-zero model (MATLAB ``tfest(data, 2, 1)``).
+    n : int
+        Metric contour resolution. 256 is accurate for low-order systems.
+    center : bool
+        Subtract each trajectory's mean before fitting (recommended).
+    min_r2 : float or None
+        Fit-quality gate threshold. Only edges where a real relationship holds
+        are tested; None disables gating.
+    gate : {'either', 'both', 'mean'}
+        How the per-condition fit qualities are combined for the gate:
+          * 'either' (default) - keep the edge if the best replicate fit in
+            EITHER condition reaches min_r2 (catches relationships that appear
+            or disappear between conditions).
+          * 'both' - require the best replicate fit in BOTH conditions to reach
+            min_r2 (a relationship present in both, whose dynamics may differ).
+          * 'mean' - use the mean R^2 over all replicate fits of both
+            conditions.
+    include_pairs : iterable[(src, tgt)] or None
+        Restrict to specific ordered edges (e.g. a prescreened candidate set).
+        If None, all ordered pairs i != j are tested.
+    global_null : bool
+        Pool within-condition nu-gaps across all edges into one null and report
+        p_global / q_global (BH-FDR).
+
+    Returns
+    -------
+    pandas.DataFrame, one row per edge, sorted by significance (or nu_gap).
+    """
+    if gate not in ("either", "both", "mean"):
+        raise ValueError("gate must be 'either', 'both', or 'mean'")
+    na = int(order)
+    nb = 0 if n_zeros is None else int(n_zeros)
+    variables = list(data_A.keys())
+    dt = _sample_time(t)
+
+    def as_reps(d):
+        out = {}
+        for k, v in d.items():
+            v = np.asarray(v, dtype=float)
+            if v.ndim == 1:
+                v = v[None, :]
+            out[k] = _center(v) if center else v
+        return out
+
+    A = as_reps(data_A)
+    B = as_reps(data_B)
+
+    if include_pairs is None:
+        pairs = [(i, j) for i in variables for j in variables if i != j]
+    else:
+        pairs = list(include_pairs)
+
+    records = []
+    global_within = []
+    for e, (src, tgt) in enumerate(pairs):
+        if progress and e % 5000 == 0:
+            print(f"  {e}/{len(pairs)} edges")
+
+        mA, r2A = _edge_models(A[src], A[tgt], t, dt, na, nb)
+        mB, r2B = _edge_models(B[src], B[tgt], t, dt, na, nb)
+        if not mA or not mB:
+            continue
+
+        # Only test an edge where a real relationship exists; otherwise the
+        # meaningless, high-variance fits would pollute the null. How the two
+        # conditions' fit qualities are combined is controlled by `gate`.
+        best_A = max(r2A, default=-np.inf)
+        best_B = max(r2B, default=-np.inf)
+        if gate == "either":
+            gate_stat = max(best_A, best_B)
+        elif gate == "both":
+            gate_stat = min(best_A, best_B)
+        else:  # 'mean'
+            gate_stat = float(np.mean(r2A + r2B)) if (r2A or r2B) else -np.inf
+        if min_r2 is not None and gate_stat < min_r2:
+            continue
+        max_r2 = max(best_A, best_B)
+
+        models = mA + mB
+        nA = len(mA)
+        idxA, idxB = range(nA), range(nA, len(models))
+        gp = _gap_pairs(models, n)
+
+        def get(i, j):
+            return gp[(i, j)] if i < j else gp[(j, i)]
+
+        between = [get(a, b) for a in idxA for b in idxB]
+        within_A = [get(a, b) for a, b in itertools.combinations(idxA, 2)]
+        within_B = [get(a, b) for a, b in itertools.combinations(idxB, 2)]
+        within = within_A + within_B
+
+        between_med = float(np.median(between))
+        within_med = float(np.median(within)) if within else 0.0
+        rec = {
+            "source": src, "target": tgt,
+            "nu_gap": between_med,
+            "within_median": within_med,
+            "separation": between_med - within_med,
+            "n_reps": min(nA, len(mB)),
+            "max_r2": float(max_r2),
+            "mean_r2": float(np.mean(r2A + r2B)) if (r2A or r2B) else np.nan,
+        }
+        records.append(rec)
+        if global_null:
+            # A within-condition gap belongs in the null only if a real
+            # relationship exists in that condition; otherwise we would be
+            # pooling the variance of fitting noise to noise, which inflates
+            # the null and destroys power (e.g. a condition where the gene
+            # went flat). Set null_from_reliable_only=False to pool all.
+            thr = -np.inf if (min_r2 is None or not null_from_reliable_only) else min_r2
+            if best_A >= thr:
+                global_within.extend(within_A)
+            if best_B >= thr:
+                global_within.extend(within_B)
+
+    df = pd.DataFrame.from_records(records)
+    if df.empty:
+        return df
+
+    if global_null and global_within:
+        pool = np.sort(np.asarray(global_within, dtype=float))
+        m = pool.size
+        ge = m - np.searchsorted(pool, df["nu_gap"].values, side="left")
+        df["p_global"] = (ge + 1) / (m + 1)
+        df["q_global"] = _bh_fdr(df["p_global"].values)
+        df = df.sort_values("q_global", ascending=True).reset_index(drop=True)
+    else:
+        df = df.sort_values("nu_gap", ascending=False).reset_index(drop=True)
+    return df