falsesync 0.1.2__py3-none-any.whl

falsesync/simengine.py

@@ -0,0 +1,277 @@
+"""Phase-3 config-driven simulation engine (see simulation_design.md).
+
+A SimConfig fully specifies one simulation cell; simulate() returns a Panel
+plus ground-truth regime/timing metadata. All randomness flows through one
+seeded numpy Generator.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from scipy.stats import t as t_dist
+
+from .aggregation import weighted_aggregate
+from .simulation import Panel, sample_taus, simulate_panel
+from .transitions import g
+
+REGIMES = (
+    "synchronous",
+    "near_synchronous",
+    "diffuse",
+    "two_cluster",
+    "three_cluster",
+    "no_transition",
+)
+
+F_FAMILIES = (
+    "degenerate", "narrow_normal", "broad_normal", "uniform", "skewed",
+    "two_normal_mix", "three_normal_mix", "spike_diffuse", "heavy_tail",
+)
+
+NOISE_KINDS = ("iid", "t3", "heterosk", "ar1", "seasonal")
+WEIGHT_KINDS = ("equal", "static", "timing_corr", "timevarying")
+MISS_KINDS = ("complete", "mcar", "dropout", "late_entry", "informative")
+
+
+@dataclass
+class SimConfig:
+    n_units: int = 100
+    n_t: int = 120
+    t_span: tuple = (0.0, 10.0)
+    regime: str = "diffuse"
+    f_family: str = "broad_normal"
+    f_params: dict = field(default_factory=dict)  # overrides, e.g. {"sigma":0.8}
+    center: float = 5.0  # central transition time
+    shape: str = "logistic"  # step/logistic/probit/linear
+    amplitude: float = 1.0  # effect size (low 0.5, med 1.0, high 2.0 typical)
+    width: float = 0.4  # transition width h
+    noise_kind: str = "iid"
+    noise_sd: float = 0.15
+    noise_params: dict = field(default_factory=dict)
+    weight_kind: str = "equal"
+    weight_params: dict = field(default_factory=dict)
+    miss_kind: str = "complete"
+    miss_params: dict = field(default_factory=dict)
+    amp_hetero: float = 0.0  # sd of A_i / A
+    width_hetero: float = 0.0  # sd of h_i / h
+    base_hetero: float = 0.0  # sd of a_i
+    trend_kind: str = "none"  # none/linear/nonlinear/local_drift/mixed
+    trend_scale: float = 0.0  # sd of trend slope per unit
+    noisevar_hetero: float = 0.0
+    seed: int = 0
+    cell_id: str = ""
+
+
+def f_tau_spec(cfg: SimConfig) -> dict:
+    """Translate (regime, f_family, f_params) into a sample_taus spec."""
+    c = cfg.center
+    p = dict(cfg.f_params)
+    if cfg.regime == "no_transition":
+        return {"kind": "degenerate_at", "center": c}  # unused
+    fam = cfg.f_family
+    if fam == "degenerate" or cfg.regime == "synchronous":
+        sd = p.get("sigma", 1e-6)
+        return {"kind": "normal", "mu": c, "sigma": sd}
+    if fam == "narrow_normal":
+        return {"kind": "normal", "mu": c, "sigma": p.get("sigma", 0.2)}
+    if fam == "broad_normal":
+        return {"kind": "normal", "mu": c, "sigma": p.get("sigma", 0.9)}
+    if fam == "uniform":
+        lo, hi = p.get("lo", c - 2.0), p.get("hi", c + 2.0)
+        return {"kind": "uniform", "lo": lo, "hi": hi}
+    if fam == "skewed":
+        return {"kind": "gamma", "shape": p.get("shape", 3.0),
+                "scale": p.get("scale", 0.5), "shift": c - 1.5}
+    if fam == "two_normal_mix":
+        d = p.get("delta", 2.5)
+        return {"kind": "mixture", "pi": p.get("pi", 0.5), "mu1": c - d / 2,
+                "mu2": c + d / 2, "sigma": p.get("sigma", 0.4)}
+    if fam == "three_normal_mix":
+        d = p.get("delta", 2.0)
+        return {"kind": "three_mix", "mu1": c - d, "mu2": c, "mu3": c + d,
+                "sigma": p.get("sigma", 0.35),
+                "pis": p.get("pis", [0.33, 0.34, 0.33])}
+    if fam == "spike_diffuse":
+        return {"kind": "spike", "center": c, "eps": p.get("eps", 0.4),
+                "lo": c - 2.5, "hi": c + 2.5}
+    if fam == "heavy_tail":
+        return {"kind": "student_t", "df": p.get("df", 3.0), "mu": c,
+                "sigma": p.get("sigma", 0.5)}
+    raise ValueError(f"unknown f_family {fam!r}")
+
+
+def sample_taus_cfg(cfg: SimConfig, rng: np.random.Generator) -> np.ndarray:
+    spec = f_tau_spec(cfg)
+    kind = spec["kind"]
+    if kind == "degenerate_at":
+        return np.full(cfg.n_units, cfg.center)
+    if kind == "three_mix":
+        pis = np.asarray(spec["pis"], dtype=float)
+        comp = rng.choice(3, cfg.n_units, p=pis / pis.sum())
+        mus = np.array([spec["mu1"], spec["mu2"], spec["mu3"]])
+        return mus[comp] + rng.normal(0, spec["sigma"], cfg.n_units)
+    if kind == "student_t":
+        return spec["mu"] + spec["sigma"] * t_dist.rvs(spec["df"], size=cfg.n_units, random_state=rng)
+    return sample_taus(cfg.n_units, spec, rng)
+
+
+def regime_truth(cfg: SimConfig) -> str:
+    if cfg.regime in REGIMES:
+        return cfg.regime
+    return cfg.regime
+
+
+def make_weights(cfg: SimConfig, taus: np.ndarray, t: np.ndarray,
+                 rng: np.random.Generator) -> np.ndarray:
+    """(n_units, n_t) observation-independent weight matrix."""
+    n = taus.size
+    kind = cfg.weight_kind
+    p = cfg.weight_params
+    if kind == "equal":
+        return np.ones((n, t.size))
+    if kind == "static":
+        w = rng.lognormal(0, p.get("sd", 0.8), n)
+        return np.tile(w / w.mean(), (t.size, 1)).T
+    if kind == "timing_corr":
+        kappa = p.get("kappa", 1.0)
+        w = np.exp(-kappa * (taus - taus.mean()) / max(taus.std(), 1e-9))
+        return np.tile(w / w.mean(), (t.size, 1)).T
+    if kind == "timevarying":
+        base = rng.lognormal(0, p.get("sd", 0.5), n)
+        ramp = np.exp(p.get("slope", 0.3) * (t[None, :] - t.mean()) / np.ptp(t) * taus[:, None])
+        w = base[:, None] * ramp
+        return w / w.mean(axis=0, keepdims=True)
+    raise ValueError(f"unknown weight_kind {kind!r}")
+
+
+def make_windows(cfg: SimConfig, taus: np.ndarray, t: np.ndarray,
+                 rng: np.random.Generator) -> np.ndarray:
+    """(n_units, 2) [L,U] windows; NaN marks unobserved in simulate."""
+    n = taus.size
+    lo, hi = t.min(), t.max()
+    win = np.tile([lo, hi], (n, 1)).astype(float)
+    kind = cfg.miss_kind
+    p = cfg.miss_params
+    if kind == "complete":
+        return win
+    if kind == "mcar":
+        rate = p.get("rate", 0.1)
+        # handled as point-wise missing in simulate()
+        return win
+    if kind == "dropout":
+        rate = p.get("rate", 0.3)
+        drop = rng.random(n) < rate
+        win[drop, 1] = np.sort(t)[rng.integers(len(t) // 3, len(t) - 1, drop.sum())]
+        return win
+    if kind == "late_entry":
+        rate = p.get("rate", 0.3)
+        late = rng.random(n) < rate
+        win[late, 0] = np.sort(t)[rng.integers(1, len(t) // 2, late.sum())]
+        return win
+    if kind == "informative":
+        kappa = p.get("kappa", 1.0)
+        # entry time correlated with tau_i: later-transitioning units enter later
+        win[:, 0] = np.clip(taus - p.get("lead", 1.0) + rng.normal(0, 0.3, n), lo, hi)
+        return win
+    raise ValueError(f"unknown miss_kind {kind!r}")
+
+
+def add_trend(cfg: SimConfig, values: np.ndarray, t: np.ndarray,
+              rng: np.random.Generator) -> np.ndarray:
+    """Add b_i(t) heterogeneity to panel values (in-place safe copy)."""
+    v = values.copy()
+    n = v.shape[0]
+    s = cfg.trend_scale
+    if cfg.trend_kind == "none" or s == 0:
+        return v
+    tc = (t - t.mean()) / np.ptp(t)
+    if cfg.trend_kind == "linear":
+        slopes = rng.normal(0, s, n)
+        v += slopes[:, None] * tc[None, :]
+    elif cfg.trend_kind == "nonlinear":
+        for i in range(n):
+            knots = rng.normal(0, s, 3)
+            v[i] += knots[0] * tc + knots[1] * tc**2 * 4 + knots[2] * np.sin(2 * np.pi * tc)
+    elif cfg.trend_kind == "local_drift":
+        for i in range(n):
+            onset = rng.uniform(t.min(), t.max())
+            drift = np.where(t >= onset, rng.normal(0, s), 0.0)
+            v[i] += drift * (t - onset)
+    elif cfg.trend_kind == "mixed":
+        slopes = rng.normal(0, s, n)
+        wobble = rng.normal(0, s * 0.5, n)[:, None] * np.sin(4 * np.pi * tc)[None, :]
+        v += slopes[:, None] * tc[None, :] + wobble
+    else:
+        raise ValueError(f"unknown trend_kind {cfg.trend_kind!r}")
+    return v
+
+
+def add_noise(cfg: SimConfig, values: np.ndarray, t: np.ndarray,
+              rng: np.random.Generator) -> np.ndarray:
+    n, nt = values.shape
+    sd = cfg.noise_sd
+    p = cfg.noise_params
+    if sd == 0:
+        return values
+    if cfg.noise_kind == "iid":
+        e = rng.normal(0, sd, (n, nt))
+    elif cfg.noise_kind == "t3":
+        e = sd * t_dist.rvs(3, size=(n, nt), random_state=rng)
+    elif cfg.noise_kind == "heterosk":
+        e = rng.normal(0, sd * (0.5 + t[None, :] / np.ptp(t)), (n, nt))
+    elif cfg.noise_kind == "ar1":
+        rho = p.get("rho", 0.7)
+        e = np.zeros((n, nt))
+        eps = rng.normal(0, sd, (n, nt))
+        e[:, 0] = eps[:, 0]
+        for k in range(1, nt):
+            e[:, k] = rho * e[:, k - 1] + eps[:, k]
+    elif cfg.noise_kind == "seasonal":
+        e = rng.normal(0, sd, (n, nt)) + sd * 0.8 * np.sin(2 * np.pi * p.get("period", 0.4) * t[None, :])
+    else:
+        raise ValueError(cfg.noise_kind)
+    if cfg.noisevar_hetero > 0:
+        e = e * rng.lognormal(0, cfg.noisevar_hetero, n)[:, None]
+    return values + e
+
+
+def simulate(cfg: SimConfig) -> tuple[Panel, dict]:
+    """Full cell simulation -> (Panel, truth dict)."""
+    rng = np.random.default_rng(cfg.seed)
+    t = np.linspace(cfg.t_span[0], cfg.t_span[1], cfg.n_t)
+    taus = sample_taus_cfg(cfg, rng)
+    n = cfg.n_units
+    A = cfg.amplitude * rng.lognormal(0, cfg.amp_hetero, n)
+    h = cfg.width * rng.lognormal(0, cfg.width_hetero, n)
+    a = rng.normal(0, cfg.base_hetero, n)
+    if cfg.regime == "no_transition":
+        A = np.zeros(n)
+    u = (t[None, :] - taus[:, None]) / h[:, None]
+    values = a[:, None] + A[:, None] * g(u, cfg.shape)
+    values = add_trend(cfg, values, t, rng)
+    values = add_noise(cfg, values, t, rng)
+    win = make_windows(cfg, taus, t, rng)
+    obs = (t[None, :] >= win[:, 0:1]) & (t[None, :] <= win[:, 1:2])
+    values = np.where(obs, values, np.nan)
+    if cfg.miss_kind == "mcar":
+        drop = rng.random(values.shape) < cfg.miss_params.get("rate", 0.1)
+        values = np.where(drop, np.nan, values)
+    w = make_weights(cfg, taus, t, rng)
+    w_t = np.where(np.isfinite(values), w, np.nan)
+    agg = np.nansum(values * w_t, axis=0) / np.maximum(np.nansum(w_t, axis=0), 1e-12)
+    panel = Panel(
+        t=t, values=values, taus=taus, weights=w.mean(axis=1), windows=win,
+        shape=cfg.shape, amplitudes=A,
+        meta={"baseline": a, "width": h, "config": cfg},
+    )
+    truth = {
+        "regime": regime_truth(cfg),
+        "tau_sd": float(np.std(taus)),
+        "tau_iqr": float(np.quantile(taus, 0.75) - np.quantile(taus, 0.25)),
+        "taus": taus,
+        "aggregate": agg,
+        "cell_id": cfg.cell_id,
+    }
+    return panel, truth

falsesync/simulation.py

@@ -0,0 +1,110 @@
+"""Timing simulation and panel generation (model ladder S1-S7)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from scipy.stats import gamma as gamma_dist
+from scipy.stats import norm
+
+from .transitions import g
+
+
+@dataclass
+class Panel:
+    t: np.ndarray
+    values: np.ndarray  # (n_units, n_t)
+    taus: np.ndarray
+    weights: np.ndarray  # (n_units,) applied uniformly over t
+    windows: np.ndarray  # (n_units, 2) [L_i, U_i]
+    shape: str
+    amplitudes: np.ndarray
+    meta: dict = field(default_factory=dict)
+
+
+def sample_taus(n: int, spec: dict, rng: np.random.Generator) -> np.ndarray:
+    """Sample transition times from a timing spec.
+
+    kinds: normal {mu,sigma}, mixture {pi,mu1,mu2,sigma1,sigma2},
+    gamma {shape,scale,shift}, uniform {lo,hi}, spike {center,eps,lo,hi}.
+    """
+    kind = spec.get("kind", "normal")
+    if kind == "normal":
+        return rng.normal(spec["mu"], spec["sigma"], n)
+    if kind == "mixture":
+        pick = rng.random(n) < spec.get("pi", 0.5)
+        out = np.empty(n)
+        out[pick] = rng.normal(spec["mu1"], spec.get("sigma1", spec.get("sigma", 0.3)), pick.sum())
+        out[~pick] = rng.normal(
+            spec["mu2"], spec.get("sigma2", spec.get("sigma", 0.3)), (~pick).sum()
+        )
+        return out
+    if kind == "gamma":
+        return spec.get("shift", 0.0) + gamma_dist.rvs(
+            spec["shape"], scale=spec["scale"], size=n, random_state=rng
+        )
+    if kind == "uniform":
+        return rng.uniform(spec["lo"], spec["hi"], n)
+    if kind == "spike":
+        eps = spec.get("eps", 0.2)
+        out = np.where(rng.random(n) < 1 - eps, spec["center"], np.nan)
+        mask = np.isnan(out)
+        out[mask] = rng.uniform(spec["lo"], spec["hi"], mask.sum())
+        return out
+    raise ValueError(f"unknown tau spec kind {kind!r}")
+
+
+def simulate_panel(
+    t: np.ndarray,
+    taus: np.ndarray,
+    shape: str = "logistic",
+    amplitude: float | np.ndarray = 1.0,
+    baseline: float | np.ndarray = 0.0,
+    width: float | np.ndarray = 0.3,
+    noise_sd: float = 0.0,
+    weights: np.ndarray | None = None,
+    windows: np.ndarray | None = None,
+    rng: np.random.Generator | None = None,
+) -> Panel:
+    """S2-style homogeneous-shape panel: Y_i(t) = a_i + A_i g((t-tau_i)/h_i) + eps."""
+    rng = rng or np.random.default_rng()
+    t = np.asarray(t, dtype=float)
+    taus = np.asarray(taus, dtype=float)
+    n = taus.size
+    A = np.broadcast_to(np.asarray(amplitude, dtype=float), (n,))
+    a = np.broadcast_to(np.asarray(baseline, dtype=float), (n,))
+    h = np.broadcast_to(np.asarray(width, dtype=float), (n,))
+    u = (t[None, :] - taus[:, None]) / h[:, None]
+    values = a[:, None] + A[:, None] * g(u, shape)
+    if noise_sd > 0:
+        values = values + rng.normal(0, noise_sd, values.shape)
+    w = np.ones(n) if weights is None else np.asarray(weights, dtype=float)
+    win = (
+        np.column_stack([np.full(n, t.min()), np.full(n, t.max())])
+        if windows is None
+        else np.asarray(windows, dtype=float)
+    )
+    obs = (t[None, :] >= win[:, 0:1]) & (t[None, :] <= win[:, 1:2])
+    values = np.where(obs, values, np.nan)
+    return Panel(t=t, values=values, taus=taus, weights=w, windows=win, shape=shape,
+                 amplitudes=A, meta={"baseline": a, "width": h, "noise_sd": noise_sd})
+
+
+def timing_density(tau_grid: np.ndarray, spec: dict) -> np.ndarray:
+    """Population density f_tau on a grid for closed-form checks."""
+    kind = spec.get("kind", "normal")
+    tg = np.asarray(tau_grid, dtype=float)
+    if kind == "normal":
+        return norm.pdf(tg, spec["mu"], spec["sigma"])
+    if kind == "mixture":
+        pi = spec.get("pi", 0.5)
+        s1 = spec.get("sigma1", spec.get("sigma", 0.3))
+        s2 = spec.get("sigma2", spec.get("sigma", 0.3))
+        return pi * norm.pdf(tg, spec["mu1"], s1) + (1 - pi) * norm.pdf(tg, spec["mu2"], s2)
+    if kind == "uniform":
+        return np.where((tg >= spec["lo"]) & (tg <= spec["hi"]),
+                        1.0 / (spec["hi"] - spec["lo"]), 0.0)
+    if kind == "gamma":
+        return gamma_dist.pdf(tg - spec.get("shift", 0.0), spec["shape"], scale=spec["scale"])
+    raise ValueError(f"no analytic density for kind {kind!r}")

falsesync/transitions.py

@@ -0,0 +1,56 @@
+"""Unit transition shapes g(u), u = (t - tau)/h, in [0, 1].
+
+All supported shapes satisfy the antisymmetry identity g(u) + g(-u) = 1
+required by proposition P2, except `linear` which satisfies it on the
+saturated extension used here.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.stats import norm
+
+SHAPES = ("step", "logistic", "probit", "linear")
+
+
+def g(u: np.ndarray, shape: str = "logistic") -> np.ndarray:
+    """Transition function values. `u` is already standardized."""
+    u = np.asarray(u, dtype=float)
+    if shape == "step":
+        out = (u >= 0).astype(float)
+        out[u == 0] = 0.5  # antisymmetric convention; measure-zero for integrals
+        return out
+    if shape == "logistic":
+        return 1.0 / (1.0 + np.exp(-u))
+    if shape == "probit":
+        return norm.cdf(u)
+    if shape == "linear":
+        return np.clip(0.5 + u / 2.0, 0.0, 1.0)
+    raise ValueError(f"unknown transition shape {shape!r}; choose from {SHAPES}")
+
+
+def g_prime(u: np.ndarray, shape: str = "logistic") -> np.ndarray:
+    """Derivative of the transition (density kernel used by P8 ill-posedness).
+
+    For `step` this is a Dirac delta conceptually; returns zeros except at the
+    discontinuity, where callers should use the P1 identity directly.
+    """
+    u = np.asarray(u, dtype=float)
+    if shape == "step":
+        out = np.full(u.shape, np.inf)
+        out[u != 0] = 0.0
+        return out
+    if shape == "logistic":
+        s = g(u, "logistic")
+        return s * (1.0 - s)
+    if shape == "probit":
+        return norm.pdf(u)
+    if shape == "linear":
+        return np.where(np.abs(u) < 1.0, 0.5, 0.0)
+    raise ValueError(f"unknown transition shape {shape!r}")
+
+
+def is_antisymmetric(shape: str) -> bool:
+    """Whether g(u) + g(-u) = 1 holds for this shape (P2 condition)."""
+    u = np.linspace(-8, 8, 401)
+    return bool(np.allclose(g(u, shape) + g(-u, shape), 1.0, atol=1e-12))

falsesync-0.1.2.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: falsesync
+Version: 0.1.2
+Summary: Aggregation-induced false synchrony: estimands, diagnostics, and simulation for change-point analysis on aggregated panels
+Author: Tatsuki Onishi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bougtoir/falsesync
+Project-URL: Source, https://github.com/bougtoir/falsesync
+Project-URL: Issues, https://github.com/bougtoir/falsesync/issues
+Project-URL: Changelog, https://github.com/bougtoir/falsesync/blob/main/CHANGELOG.md
+Project-URL: DOI, https://doi.org/10.5281/zenodo.23233536
+Keywords: change-point analysis,aggregation,synchrony,panel time series,calibration
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.4,>=2.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: pandas>=2.0
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: joblib>=1.3
+Requires-Dist: pyyaml>=6
+Requires-Dist: scikit-learn<1.8,>=1.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: black>=24; extra == "dev"
+Provides-Extra: cp
+Requires-Dist: ruptures>=1.1; extra == "cp"
+Dynamic: license-file
+
+# falsesync
+
+Diagnostics for aggregation-induced false synchrony in change-point analysis.
+
+## Scientific motivation
+
+Many engineering and observational studies average a panel of unit-level
+series (turbines, battery cells, sensors, regions) and then fit a change point
+to the aggregate. A sharp aggregate breakpoint is easily read as evidence that
+the units changed together. That reading is not justified in general: when
+unit transitions occur at heterogeneous times \(\tau_i \sim F_\tau\), the
+aggregate mean is a smoothed curve \(m(t) = a + A\,(g * F_\tau)(t)\) that can
+still produce a well-defined, strong breakpoint. The fitted aggregate
+breakpoint is a functional \(T_M(F_\tau, g, w, \text{window}, \text{noise})\)
+that depends on the breakpoint operator \(M\), the observation window, the
+weights, the observation process, and the noise, and it need not coincide with
+the mean, median, or mode of the timing distribution.
+
+## What falsesync does
+
+- simulates unit-level transition panels with configurable timing laws,
+  transition shapes, weights, observation windows, trends, and noise;
+- computes weighted aggregates and aggregate breakpoints under several
+  operators (least squares, maximum slope, CUSUM, binary segmentation) and
+  reports the spread across operators;
+- estimates unit-level breakpoints with bootstrap uncertainty and a
+  floor-corrected timing dispersion
+  \(\mathrm{sd}_{\mathrm{corr}} = \sqrt{\max(\mathrm{sd}^2(\hat\tau_i) - \bar s^2, 0)}\);
+- returns calibrated probabilities for five timing regimes
+  (`SYNCHRONOUS`, `NEAR_SYNCHRONOUS`, `DIFFUSE_ASYNCHRONOUS`, `CLUSTERED`,
+  `NO_TRANSITION`) from a classifier calibrated on a separate simulation grid;
+- issues a false common-event warning when the aggregate break is strong but
+  the calibrated probability of synchrony is low, plus warnings for trend
+  confounding, operator dependence, and observation-process risks.
+
+## What falsesync does not claim
+
+- It is not a causal method and does not identify what caused any transition.
+- A low synchrony probability is a warning that the aggregate break should not
+  be read as a common event; it is not a test that rejects synchrony.
+- The regime probabilities are calibrated only for data-generating conditions
+  resembling the calibration grid (see `simulations/configs/`).
+
+## Known limitations
+
+- Informative observation processes (entry or dropout related to transition
+  timing) can create apparent synchrony; this failure mode is detectable in
+  simulation but not corrected by the package.
+- Trend heterogeneity across units can be confounded with timing
+  heterogeneity.
+- Unit-level break uncertainty inflates apparent timing dispersion; the
+  floor correction reduces but does not remove this effect.
+- The aggregate breakpoint location is operator-dependent; different
+  operators can give materially different locations on the same aggregate.
+- Without unit-level data, synchrony cannot be certified from the aggregate
+  alone.
+
+## Installation
+
+Python >= 3.10.
+
+```bash
+git clone https://github.com/bougtoir/falsesync.git
+cd falsesync
+pip install .            # or: pip install -e ".[dev]" for tests
+```
+
+Optional: `pip install ".[cp]"` adds `ruptures`-backed detectors. The
+reported binary-segmentation results were computed with `ruptures` 1.1.10, so
+FULL replication requires `pip install ".[dev,cp]"`.
+
+## Minimal example
+
+```bash
+python examples/minimal_example.py
+```
+
+The example simulates 80 units with diffuse (normal, SD 1.1) transition times,
+fits `FalseSynchronyModel` with the shipped calibrated classifier, and prints
+the aggregate breakpoint, the corrected timing dispersion, the five regime
+probabilities, and the warnings. In outline:
+
+```python
+import joblib
+import numpy as np
+from falsesync import simulation
+from falsesync.model import FalseSynchronyModel
+
+rng = np.random.default_rng(1)
+t = np.linspace(0, 10, 180)
+taus = simulation.sample_taus(80, {"kind": "normal", "mu": 5.0, "sigma": 1.1}, rng)
+panel = simulation.simulate_panel(t, taus, shape="logistic", amplitude=1.5,
+                                  width=0.3, noise_sd=0.2, rng=rng)
+clf = joblib.load("simulations/calibration/classifier.joblib")
+res = FalseSynchronyModel(classifier=clf).fit(t, panel.values)
+print(res.aggregate_breakpoint, res.timing_dispersion["sd_corrected"])
+print(res.regime_probabilities, res.interpretation_warning)
+```
+
+## Main workflow
+
+1. `simulations/run_grid.py` simulates a configuration grid
+   (`simulations/configs/*.yaml`) and extracts diagnostic features.
+2. `simulations/run_calibration.py` fits and temperature-calibrates the
+   regime classifier on the calibration grid
+   (`simulations/calibration/classifier.joblib`).
+3. `simulations/run_evaluation.py` evaluates the frozen classifier on the
+   locked evaluation grid.
+4. `simulations/run_stress.py`, `run_missingness_mitigation.py`, and
+   `run_near_sync.py` run the robustness and stress conditions.
+5. `simulations/run_kelmarsh.py` and `simulations/run_nasa_battery.py` run the
+   two empirical demonstrations.
+6. `simulations/make_phase3_figures.py` builds Figures 1-6.
+
+## Reproducing the Technometrics results
+
+| Mode  | Command                          | Content                                                                 | Runtime (1 CPU core) |
+|-------|----------------------------------|-------------------------------------------------------------------------|----------------------|
+| QUICK | `python replication/run_quick.py` | tests, minimal example, smoke grid, re-evaluation of the locked grid with the shipped classifier, regeneration of Figures 1-4, comparison with reference tables and figures | < 1 min |
+| FULL  | `python replication/run_full.py`  | data download and checksum verification, calibration, locked evaluation, stress tests, both empirical analyses, all figures, comparison with reference tables; needs the `cp` extra | about 15 min |
+
+Both scripts exit non-zero if any regenerated result table differs from the
+shipped reference copy. `make all` / `make quick` run the same steps.
+
+The reference figures were rendered with matplotlib 3.10. matplotlib 3.11
+reproduces every result table exactly but renders Figures 1-4 with small
+pixel differences, which the QUICK figure comparison reports as `DIFFERS`;
+use `pip install "matplotlib<3.11"` for a pixel-level figure match.
+
+**Locked evaluation.** `simulations/configs/evaluation_locked.yaml` (seeds
+3000-3999) was fixed and committed before the evaluation was run and was not
+edited afterwards; its SHA-256 is recorded in `simulations/configs/SHA256SUMS`.
+The calibration grid (`calibration.yaml`) and the development grid
+(`development.yaml`) use disjoint seed ranges. `METHOD_FREEZE.md` lists the
+frozen thresholds and method choices.
+
+**Traceability.** `manuscript_number_trace.csv` maps every number reported in
+the manuscript to the result file and column that produces it;
+`figure_manifest.csv` and `table_manifest.csv` map figures and tables to their
+generating scripts and inputs.
+
+## Data acquisition
+
+No raw data are redistributed in this repository. `python fetch_data.py`
+downloads the two public datasets from their original repositories, verifies
+each file against the SHA-256 recorded in `data/acquisition_ledger.csv`, and
+extracts the files used by the analyses into `data/raw/` (git-ignored). See
+`data/README.md` for sources, licenses, and citations.
+
+## Repository structure
+
+```text
+src/falsesync/        package source
+tests/                unit tests (theory identities, workflow)
+examples/             minimal example
+simulations/          simulation, calibration, evaluation, empirical scripts
+  configs/            development, calibration, locked evaluation grids
+  calibration/        calibrated classifier artifact
+  results/            simulated grid outputs
+replication/          QUICK and FULL replication entry points
+proofs/               proofs of propositions P1-P8
+outputs/              reference figures
+data/                 acquisition ledger and data documentation
+*.csv                 reference result tables
+math_specification.md, diagnostic_specification.md, METHOD_FREEZE.md,
+counterexamples.md    method documentation
+```
+
+## Citation
+
+See `CITATION.cff`. Please cite the software and the accompanying manuscript:
+T. Onishi, "Aggregation-Induced False Synchrony in Change-Point Analysis"
+(manuscript submitted to *Technometrics*).
+
+## License
+
+MIT (see `LICENSE`). Data obtained through `fetch_data.py` remain under their
+original licenses (see `data/README.md`).
+
+## Manuscript status
+
+Version 0.1.2 corresponds to the manuscript as submitted to *Technometrics*.
+The manuscript has not been peer reviewed or accepted.