falsesync 0.1.2__py3-none-any.whl

falsesync/__init__.py

@@ -0,0 +1,9 @@
+"""falsesync — aggregation-induced false synchrony diagnostics.
+
+Core model: Y_i(t) = a_i + b_i(t) + A_i g_i((t - tau_i)/h_i) + eps_i(t).
+The aggregate breakpoint is an operator-dependent functional
+T_M(F_tau, g, w, ...) which in general equals no moment of F_tau.
+See math_specification.md and proofs/ for P1-P8.
+"""
+
+__version__ = "0.1.2"

falsesync/aggregation.py

@@ -0,0 +1,85 @@
+"""Weighted aggregation and the population convolution m(t)."""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.stats import norm
+
+from .transitions import g
+
+
+def weighted_aggregate(
+    values: np.ndarray, weights: np.ndarray | None = None
+) -> np.ndarray:
+    """Row-weighted mean over units, respecting NaN observation windows.
+
+    values: (n_units, n_t); weights: (n_units,) constant over t, or
+    (n_units, n_t) for time-varying weights w_i(t).
+    Implements m_obs(t) = sum_i w_i 1{obs} Y_i / sum_i w_i 1{obs} (P5).
+    """
+    v = np.asarray(values, dtype=float)
+    n = v.shape[0]
+    if weights is None:
+        w = np.ones((n, 1))
+    else:
+        w = np.asarray(weights, dtype=float)
+        if w.ndim == 1:
+            w = w[:, None]
+        elif w.shape != v.shape:
+            raise ValueError(
+                f"2D weights must match values shape {v.shape}, got {w.shape}"
+            )
+    obs = np.isfinite(v)
+    wv = np.where(obs, v * w, 0.0)
+    denom = np.where(obs, w, 0.0).sum(axis=0)
+    with np.errstate(invalid="ignore", divide="ignore"):
+        return np.where(denom > 0, wv.sum(axis=0) / denom, np.nan)
+
+
+def timing_cdf(tau_grid: np.ndarray, spec: dict) -> np.ndarray:
+    """Population F_tau on a grid (used by the P1/P5 identities)."""
+    from .simulation import timing_density
+
+    tg = np.asarray(tau_grid, dtype=float)
+    f = timing_density(tg, spec)
+    c = np.concatenate([[0.0], np.cumsum((f[:-1] + f[1:]) / 2 * np.diff(tg))])
+    return np.clip(c / c[-1], 0, 1)
+
+
+def population_m(
+    t: np.ndarray,
+    spec: dict,
+    shape: str = "logistic",
+    amplitude: float = 1.0,
+    baseline: float = 0.0,
+    width: float = 0.3,
+    tau_grid: np.ndarray | None = None,
+) -> np.ndarray:
+    """Population mean curve a + A * (g * f_tau)(t) via quadrature.
+
+    Closed forms used when available: step g -> F_tau(t) (P1);
+    probit + normal -> Phi((t-mu)/sqrt(1+sigma^2)) with unit width (P3a).
+    """
+    t = np.asarray(t, dtype=float)
+    kind = spec.get("kind", "normal")
+    if shape == "step" and kind in ("normal", "mixture", "uniform"):
+        return baseline + amplitude * np.interp(
+            t, np.asarray(tau_grid if tau_grid is not None else t),
+            timing_cdf(np.asarray(tau_grid if tau_grid is not None else t), spec),
+        )
+    if shape == "probit" and kind == "normal" and width == 1.0:
+        return baseline + amplitude * norm.cdf(
+            (t - spec["mu"]) / np.sqrt(1 + spec["sigma"] ** 2)
+        )
+    tg = (
+        np.asarray(tau_grid, dtype=float)
+        if tau_grid is not None
+        else np.linspace(t.min() - 8 * width, t.max() + 8 * width, 4001)
+    )
+    from .simulation import timing_density
+
+    f = timing_density(tg, spec)
+    u = (t[:, None] - tg[None, :]) / width
+    trapz = getattr(np, "trapezoid", np.trapz)
+    conv = trapz(g(u, shape) * f[None, :], tg, axis=1)
+    return baseline + amplitude * conv

falsesync/alignment.py

@@ -0,0 +1,37 @@
+"""Event-time realignment (alignment in unit-specific transition time)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def event_time_realign(
+    t: np.ndarray, values: np.ndarray, taus: np.ndarray
+) -> np.ndarray:
+    """Re-express each unit series in event time s = t - tau_i.
+
+    Returns an (n, 2k+1) array on a common event-time grid centered at 0;
+    NaN where a unit's observed window does not cover s.
+    """
+    t = np.asarray(t, dtype=float)
+    taus = np.asarray(taus, dtype=float)
+    dt = float(np.median(np.diff(t)))
+    half = float(np.minimum(taus - t.min(), t.max() - taus).max())
+    k = int(half / dt)
+    s_grid = np.arange(-k, k + 1) * dt
+    out = np.full((values.shape[0], s_grid.size), np.nan)
+    for i in range(values.shape[0]):
+        src_t = s_grid + taus[i]
+        valid = (src_t >= t.min()) & (src_t <= t.max())
+        out[i, valid] = np.interp(src_t[valid], t, values[i])
+    return out
+
+
+def realign_summary(aligned: np.ndarray, s_dt: float) -> dict:
+    """Aligned-panel summary for the diagnostic's event_aligned_summary."""
+    agg = np.nanmean(aligned, axis=0)
+    d = np.gradient(np.nan_to_num(agg, nan=np.nanmean(agg[np.isfinite(agg)])), s_dt)
+    return {
+        "aligned_max_slope": float(np.nanmax(np.abs(d))),
+        "coverage": float(np.isfinite(aligned).mean()),
+    }

falsesync/changepoints.py

@@ -0,0 +1,146 @@
+"""Breakpoint operators T_M on a univariate series.
+
+Each operator returns a BreakResult; the `method` tag identifies which
+estimand was computed (see breakpoint_operator_comparison.md). ruptures is
+used when installed; every method has a graceful fallback.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+
+@dataclass
+class BreakResult:
+    location: float
+    index: int
+    strength: float  # (mean_R - mean_L) / sigma_hat
+    method: str
+    extras: dict = field(default_factory=dict)
+
+
+def ls_breakpoint(t: np.ndarray, y: np.ndarray) -> BreakResult:
+    """Single least-squares break in the mean (piecewise-constant model)."""
+    t = np.asarray(t, dtype=float)
+    y = np.asarray(y, dtype=float)
+    ok = np.isfinite(y)
+    t, y = t[ok], y[ok]
+    n = y.size
+    cum1 = np.concatenate([[0.0], np.cumsum(y)])
+    cum2 = np.concatenate([[0.0], np.cumsum(y * y)])
+
+    def sse(c: int) -> float:
+        l_sum, l_sq = cum1[c], cum2[c]
+        r_sum, r_sq = cum1[n] - cum1[c], cum2[n] - cum2[c]
+        l_sse = l_sq - l_sum**2 / max(c, 1)
+        r_sse = r_sq - r_sum**2 / max(n - c, 1)
+        return l_sse + r_sse
+
+    cs = np.arange(2, n - 2)
+    vals = np.array([sse(c) for c in cs])
+    c_hat = cs[int(np.argmin(vals))]
+    mean_l, mean_r = y[:c_hat].mean(), y[c_hat:].mean()
+    sigma = np.sqrt(max(sse(c_hat) / (n - 2), 1e-12))
+    return BreakResult(
+        location=float(t[c_hat]),
+        index=int(c_hat),
+        strength=float((mean_r - mean_l) / sigma),
+        method="ls",
+        extras={"mean_l": float(mean_l), "mean_r": float(mean_r), "sigma": float(sigma)},
+    )
+
+
+def maxslope_breakpoint(t: np.ndarray, y: np.ndarray) -> BreakResult:
+    """Breakpoint at argmax of the numerical derivative (T_ms)."""
+    t = np.asarray(t, dtype=float)
+    y = np.asarray(y, dtype=float)
+    ok = np.isfinite(y)
+    t, y = t[ok], y[ok]
+    d = np.gradient(y, t)
+    i = int(np.argmax(np.abs(d)))
+    return BreakResult(
+        location=float(t[i]), index=i, strength=float(d[i]), method="maxslope"
+    )
+
+
+def cusum_breakpoint(t: np.ndarray, y: np.ndarray) -> BreakResult:
+    """Single CUSUM-type breakpoint (argmax |cumulative deviation|)."""
+    t = np.asarray(t, dtype=float)
+    y = np.asarray(y, dtype=float)
+    ok = np.isfinite(y)
+    t, y = t[ok], y[ok]
+    s = np.cumsum(y - y.mean())
+    i = int(np.argmax(np.abs(s)))
+    res = ls_breakpoint(t, y)
+    return BreakResult(t[i], i, res.strength, "cusum", {"ls_location": res.location})
+
+
+def multibreak(t: np.ndarray, y: np.ndarray, n_bkps: int = 3) -> BreakResult:
+    """Penalized multi-break via binary segmentation (LS fallback).
+
+    Uses ruptures.Binseg when installed; otherwise a native binary
+    segmentation on the LS objective (same estimand family at k=1).
+    """
+    t = np.asarray(t, dtype=float)
+    y = np.asarray(y, dtype=float)
+    ok = np.isfinite(y)
+    t, y = t[ok], y[ok]
+    try:
+        import ruptures as rpt
+
+        bkps = rpt.Binseg(model="l2").fit(y).predict(n_bkps=n_bkps)
+        idx = [b for b in bkps if b < y.size]
+    except Exception:
+        idx = _native_binseg(y, n_bkps)
+    main = idx[0] if idx else ls_breakpoint(t, y).index
+    res = ls_breakpoint(t, y)
+    return BreakResult(
+        float(t[main]), main, res.strength, "binseg",
+        {"all_break_indices": idx, "all_break_locations": [float(t[i]) for i in idx]},
+    )
+
+
+def _native_binseg(y: np.ndarray, n_bkps: int) -> list[int]:
+    """Greedy binary segmentation on the LS objective."""
+    n = y.size
+    segments = [(0, n)]
+    breaks: list[int] = []
+    while len(breaks) < n_bkps:
+        best_gain, best = 0.0, None
+        for lo, hi in segments:
+            if hi - lo < 4:
+                continue
+            seg = y[lo:hi]
+            cum1 = np.concatenate([[0.0], np.cumsum(seg)])
+            cum2 = np.concatenate([[0.0], np.cumsum(seg * seg)])
+            base = cum2[-1] - cum1[-1] ** 2 / seg.size
+            for c in range(2, seg.size - 2):
+                l = cum2[c] - cum1[c] ** 2 / c
+                r = (cum2[-1] - cum2[c]) - (cum1[-1] - cum1[c]) ** 2 / (seg.size - c)
+                gain = base - l - r
+                if gain > best_gain:
+                    best_gain, best = gain, (lo, hi, lo + c)
+        if best is None:
+            break
+        lo, hi, c = best
+        breaks.append(c)
+        segments.remove((lo, hi))
+        segments.extend([(lo, c), (c, hi)])
+    return sorted(breaks)
+
+
+def aggregate_breakpoint(
+    t: np.ndarray, y: np.ndarray, method: str = "ls", **kwargs
+) -> BreakResult:
+    """Dispatch a breakpoint operator. Methods: ls, maxslope, cusum, binseg, wbs."""
+    if method == "ls":
+        return ls_breakpoint(t, y)
+    if method == "maxslope":
+        return maxslope_breakpoint(t, y)
+    if method == "cusum":
+        return cusum_breakpoint(t, y)
+    if method in ("binseg", "wbs", "pelt"):
+        return multibreak(t, y, **kwargs)
+    raise ValueError(f"unknown method {method!r}")

falsesync/datasets.py

@@ -0,0 +1,68 @@
+"""Loaders for acquired public engineering datasets.
+
+Raw snapshots live under data/raw/ (see data/acquisition_ledger.csv).
+Loaders never mutate raw files; they return tidy DataFrames.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+DATA_ROOT = Path(__file__).resolve().parents[2] / "data" / "raw"
+
+
+@dataclass
+class PanelData:
+    """Tidy panel: unit_id, t, value (+ optional weight/channel columns)."""
+
+    frame: pd.DataFrame
+    source: str
+    notes: str = ""
+
+    def to_unit_matrix(self) -> tuple[np.ndarray, np.ndarray, list[str]]:
+        """(t, values[n_units, n_t], unit_ids) wide form for diagnostics."""
+        df = self.frame
+        wide = df.pivot_table(index="unit_id", columns="t", values="value", aggfunc="mean")
+        t = wide.columns.to_numpy(dtype=float)
+        return t, wide.to_numpy(dtype=float), list(wide.index.astype(str))
+
+
+def load_nasa_battery_cycles(data_dir: Path | None = None) -> PanelData:
+    """NASA PCoE Li-ion capacity-vs-cycle per battery unit (discharge capacity)."""
+    root = (data_dir or DATA_ROOT) / "nasa_battery"
+    rows = []
+    for f in sorted(root.rglob("*.csv")):
+        df = pd.read_csv(f)
+        cap_col = next((c for c in df.columns if c.lower() in ("capacity", "discharge_capacity")), None)
+        cyc_col = next((c for c in df.columns if "cycle" in c.lower()), None)
+        if cap_col is None:
+            continue
+        unit = f.parent.name + "/" + f.stem
+        t_col = cyc_col or df.columns[0]
+        for _, r in df.iterrows():
+            rows.append({"unit_id": unit, "t": r[t_col], "value": r[cap_col]})
+    return PanelData(pd.DataFrame(rows), "nasa_pcoe_battery")
+
+
+def load_scada_power(data_dir: Path | None = None, dataset: str = "kelmarsh") -> PanelData:
+    """Kelmarsh/Penmanshiel SCADA: power output per turbine over time."""
+    root = (data_dir or DATA_ROOT) / dataset
+    rows = []
+    for f in sorted(root.rglob("*.csv")):
+        df = pd.read_csv(f, low_memory=False)
+        t_col = next((c for c in df.columns if "time" in c.lower() or "date" in c.lower()), df.columns[0])
+        p_col = next((c for c in df.columns if "power" in c.lower()), None)
+        u_col = next((c for c in df.columns if "turbine" in c.lower() or "unit" in c.lower()), None)
+        if p_col is None:
+            continue
+        uvals = df[u_col] if u_col else pd.Series(f.stem, index=df.index)
+        tt = pd.to_datetime(df[t_col], errors="coerce")
+        t_num = (tt - tt.min()).dt.total_seconds() / 86400.0
+        for u, gdf in df.assign(_t=t_num, _u=uvals).groupby("_u"):
+            for _, r in gdf.iterrows():
+                rows.append({"unit_id": str(u), "t": r["_t"], "value": r[p_col]})
+    return PanelData(pd.DataFrame(rows), f"{dataset}_scada")

falsesync/diagnostics.py

@@ -0,0 +1,265 @@
+"""False-synchrony diagnostic (see diagnostic_specification.md)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .aggregation import weighted_aggregate
+from .changepoints import BreakResult, aggregate_breakpoint
+from .inference import deconvolve_timing, unit_break_uncertainties
+
+
+@dataclass
+class FalseSynchronyResult:
+    aggregate_breakpoint: float
+    aggregate_break_strength: float
+    unit_breakpoints: np.ndarray
+    unit_breakpoint_uncertainty: np.ndarray
+    timing_distribution: dict  # {"grid": t, "density": f_hat, "deconvolved": f_dec}
+    timing_dispersion: dict  # {"sd": ..., "iqr": ..., "ci": (lo, hi)}
+    cluster_structure: dict  # {"n_components": k, "centers": [...], "weights": [...]}
+    synchrony_score: float
+    regime_probabilities: dict  # keys: SYNCHRONOUS/CLUSTERED/DIFFUSE_ASYNCHRONOUS/NO_TRANSITION
+    event_aligned_summary: dict
+    interpretation_warning: list[str]
+    method: str = "ls"
+    aggregate_break_result: BreakResult | None = None
+    components: dict = field(default_factory=dict)
+
+
+def _kde(samples: np.ndarray, grid: np.ndarray, bw: float) -> np.ndarray:
+    u = (grid[:, None] - samples[None, :]) / bw
+    k = np.exp(-0.5 * u * u) / np.sqrt(2 * np.pi)
+    return k.mean(axis=1) / bw
+
+
+def _fit_unit_breaks(
+    t: np.ndarray, values: np.ndarray, method: str = "ls"
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Per-unit LS break: (tau_hat, strength, mean_l->r jump)."""
+    n = values.shape[0]
+    taus = np.full(n, np.nan)
+    strengths = np.full(n, np.nan)
+    idxs = np.full(n, -1, dtype=int)
+    for i in range(n):
+        y = values[i]
+        if np.isfinite(y).sum() < 8:
+            continue
+        try:
+            res = aggregate_breakpoint(t, np.nan_to_num(y, nan=np.nanmean(y[np.isfinite(y)])), method)
+            taus[i] = res.location
+            strengths[i] = res.strength
+            idxs[i] = res.index
+        except Exception:
+            continue
+    return taus, strengths, idxs
+
+
+def false_synchrony_diagnostic(
+    t: np.ndarray,
+    aggregate_series: np.ndarray | None,
+    unit_values: np.ndarray | None = None,
+    weights: np.ndarray | None = None,
+    windows: np.ndarray | None = None,
+    method: str = "ls",
+    rng: np.random.Generator | None = None,
+    n_boot: int = 200,
+) -> FalseSynchronyResult:
+    """Main diagnostic entry point (spec §9/§10).
+
+    If unit_values is None, returns an aggregate-only result whose
+    interpretation_warning states synchrony cannot be certified (P6c).
+    """
+    rng = rng or np.random.default_rng(0)
+    t = np.asarray(t, dtype=float)
+    warnings: list[str] = []
+    if aggregate_series is None and unit_values is None:
+        raise ValueError("need aggregate_series or unit_values")
+    if aggregate_series is None:
+        aggregate_series = weighted_aggregate(unit_values, weights)
+    agg_res = aggregate_breakpoint(t, aggregate_series, method)
+    agg_break, agg_strength = agg_res.location, agg_res.strength
+
+    if unit_values is None:
+        return FalseSynchronyResult(
+            aggregate_breakpoint=agg_break,
+            aggregate_break_strength=agg_strength,
+            unit_breakpoints=np.array([]),
+            unit_breakpoint_uncertainty=np.array([]),
+            timing_distribution={"grid": t, "density": np.full(t.size, np.nan)},
+            timing_dispersion={"sd": np.nan, "iqr": np.nan, "ci": (np.nan, np.nan)},
+            cluster_structure={"n_components": 0, "centers": [], "weights": []},
+            synchrony_score=np.nan,
+            regime_probabilities={
+                "SYNCHRONOUS": np.nan, "CLUSTERED": np.nan,
+                "DIFFUSE_ASYNCHRONOUS": np.nan, "NO_TRANSITION": np.nan,
+            },
+            event_aligned_summary={},
+            interpretation_warning=[
+                "aggregate-only input: synchrony cannot be certified from the "
+                "aggregate curve alone (P6c); unit-level series required.",
+                "regime probabilities are not estimable without unit data.",
+            ],
+            method=method,
+            aggregate_break_result=agg_res,
+        )
+
+    taus, strengths, _ = _fit_unit_breaks(t, unit_values, method)
+    valid = np.isfinite(taus)
+    taus_v = taus[valid]
+    if taus_v.size == 0:
+        warnings.append(
+            "no estimable unit breakpoints (insufficient observations or "
+            "failed fits): synchrony cannot be certified; unit-level "
+            "fields are not estimable."
+        )
+        return FalseSynchronyResult(
+            aggregate_breakpoint=agg_break,
+            aggregate_break_strength=agg_strength,
+            unit_breakpoints=taus,
+            unit_breakpoint_uncertainty=np.full(taus.size, np.nan),
+            timing_distribution={"grid": t, "density": np.full(t.size, np.nan)},
+            timing_dispersion={"sd": np.nan, "iqr": np.nan, "ci": (np.nan, np.nan)},
+            cluster_structure={"n_components": 0, "centers": [], "weights": []},
+            synchrony_score=np.nan,
+            regime_probabilities={
+                "SYNCHRONOUS": np.nan, "CLUSTERED": np.nan,
+                "DIFFUSE_ASYNCHRONOUS": np.nan, "NO_TRANSITION": np.nan,
+            },
+            event_aligned_summary={},
+            interpretation_warning=warnings,
+            method=method,
+            aggregate_break_result=agg_res,
+        )
+    w_v = weights[valid] if weights is not None else None
+    s_i = unit_break_uncertainties(t, unit_values[valid], taus_v, rng=rng, n_boot=60)
+
+    grid = np.linspace(t.min(), t.max(), 400)
+    bw = max(1.06 * np.std(taus_v) * taus_v.size ** -0.2, (t[1] - t[0]))
+    f_hat = _kde(taus_v, grid, bw)
+    f_dec = deconvolve_timing(taus_v, s_i, grid)
+    sd = float(np.std(taus_v))
+    q = np.quantile(taus_v, [0.25, 0.75])
+    iqr = float(q[1] - q[0])
+
+    boot_sd = [
+        float(np.std(rng.choice(taus_v, taus_v.size, replace=True)))
+        for _ in range(n_boot)
+    ]
+    sd_ci = tuple(np.quantile(boot_sd, [0.025, 0.975]).tolist())
+
+    # s1: timing spread vs aggregate transition width (FWHM of m')
+    dm = np.gradient(np.nan_to_num(aggregate_series, nan=np.nanmean(aggregate_series[np.isfinite(aggregate_series)])), t)
+    half = np.max(dm) / 2
+    fwhm_idx = np.where(dm >= half)[0]
+    w_agg = float(t[fwhm_idx[-1]] - t[fwhm_idx[0]]) if fwhm_idx.size > 1 else np.inf
+    s1_width = sd / w_agg if np.isfinite(w_agg) and w_agg > 0 else np.nan
+
+    # s2: mass concentration of deconvolved density (peak share vs uniform)
+    f_dec_n = np.clip(f_dec, 0, None)
+    f_dec_n = f_dec_n / np.trapz(f_dec_n, grid) if np.trapz(f_dec_n, grid) > 0 else f_dec_n
+    peak_share = float(np.max(f_dec_n) * (grid[1] - grid[0]) * 20)
+    s2_shape = min(peak_share, 1.0)
+
+    # s3: unit break alignment — fraction of units with a detectable break
+    detectable = np.isfinite(strengths) & (np.abs(strengths) > 2.0)
+    s3_alignment = float(detectable[valid].mean()) if valid.any() else np.nan
+
+    # s4: weight-timing correlation + window-timing correlation
+    s4_parts = []
+    if w_v is not None:
+        c_w = float(np.corrcoef(w_v, taus_v)[0, 1])
+        s4_parts.append(("weight_timing_corr", c_w))
+        if abs(c_w) > 0.3:
+            warnings.append(
+                f"weight-timing correlation {c_w:+.2f}: aggregate breakpoint is "
+                "tilted toward heavily weighted units' timing (P4)."
+            )
+    if windows is not None:
+        wv = np.asarray(windows)[valid]
+        span = wv[:, 1] - wv[:, 0]
+        c_win = float(np.corrcoef(span, taus_v)[0, 1])
+        s4_parts.append(("window_timing_corr", c_win))
+        if abs(c_win) > 0.3:
+            warnings.append(
+                f"window-timing correlation {c_win:+.2f}: observed aggregate is "
+                "a convolution against a time-varying observed timing law (P5)."
+            )
+    s4_weighting = float(np.mean([abs(c) for _, c in s4_parts])) if s4_parts else 0.0
+
+    # regime probabilities (simple distance-based classifier; calibrated in Phase 3)
+    noise_floor = float(np.median(s_i)) if s_i.size else np.nan
+    excess = sd**2 - noise_floor**2 if np.isfinite(noise_floor) else sd**2
+    p_sync = float(np.clip(1 - sd / max(2 * noise_floor, 1e-9), 0, 1)) if np.isfinite(noise_floor) else np.nan
+    # crude mixture check via dip in kde between two modes
+    modes = _local_maxima(f_dec_n)
+    p_cluster = float(len(modes) >= 2) * 0.7 + (0.3 if excess > noise_floor**2 else 0.0)
+    p_diffuse = float(np.clip(sd / (0.5 * (t.max() - t.min())), 0, 1))
+    p_notrans = float(np.clip(1 - abs(agg_strength) / 5, 0, 1)) if np.isfinite(agg_strength) else np.nan
+    probs = np.array([max(p_sync, 0.01), p_cluster, p_diffuse * 0.5, p_notrans * 0.2])
+    probs = probs / probs.sum()
+    regime_probabilities = dict(zip(
+        ["SYNCHRONOUS", "CLUSTERED", "DIFFUSE_ASYNCHRONOUS", "NO_TRANSITION"],
+        [float(p) for p in probs],
+    ))
+
+    components = {
+        "s1_width": s1_width,
+        "s2_shape": s2_shape,
+        "s3_alignment": s3_alignment,
+        "s4_weighting": s4_weighting,
+    }
+    finite = [v for v in components.values() if np.isfinite(v)]
+    synchrony_score = float(np.clip(1 - np.mean(finite), 0, 1)) if finite else np.nan
+
+    if excess <= 0:
+        warnings.append(
+            "unit break-time spread is within the unit-level estimation-noise "
+            "floor; observed dispersion may be entirely measurement (CE-UNITERR)."
+        )
+    warnings.append(
+        f"LS breakpoint {agg_break:.3g} is window-dependent (P7): "
+        "do not interpret as mean/median/mode of F_tau without the FOC check."
+    )
+
+    from .alignment import event_time_realign
+
+    aligned = event_time_realign(t, unit_values[valid], taus_v)
+    event_aligned_summary = {
+        "n_aligned": int(valid.sum()),
+        "aligned_agg_sharpness": float(np.nanmax(np.abs(np.gradient(
+            np.nanmean(aligned, axis=0)[np.isfinite(np.nanmean(aligned, axis=0))]
+        )))) if valid.any() else np.nan,
+        "tau_spread_before": sd,
+        "est_noise_floor": noise_floor,
+    }
+
+    centers = [float(grid[m]) for m in modes]
+    cluster_structure = {
+        "n_components": len(modes),
+        "centers": centers,
+        "weights": [float(f_dec_n[m]) for m in modes],
+    }
+    return FalseSynchronyResult(
+        aggregate_breakpoint=agg_break,
+        aggregate_break_strength=agg_strength,
+        unit_breakpoints=taus,
+        unit_breakpoint_uncertainty=s_i,
+        timing_distribution={"grid": grid, "density": f_hat, "deconvolved": f_dec_n},
+        timing_dispersion={"sd": sd, "iqr": iqr, "ci": sd_ci},
+        cluster_structure=cluster_structure,
+        synchrony_score=synchrony_score,
+        regime_probabilities=regime_probabilities,
+        event_aligned_summary=event_aligned_summary,
+        interpretation_warning=warnings,
+        method=method,
+        aggregate_break_result=agg_res,
+        components=components,
+    )
+
+
+def _local_maxima(f: np.ndarray) -> list[int]:
+    out = [i for i in range(1, len(f) - 1) if f[i] >= f[i - 1] and f[i] >= f[i + 1]]
+    return [i for i in out if f[i] > 0.1 * f.max()] if f.size else []