falsesync 0.1.2__tar.gz

falsesync-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tatsuki Onishi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

falsesync-0.1.2/PKG-INFO

@@ -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.

falsesync-0.1.2/README.md

@@ -0,0 +1,183 @@
+# 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.

falsesync-0.1.2/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "falsesync"
+version = "0.1.2"
+description = "Aggregation-induced false synchrony: estimands, diagnostics, and simulation for change-point analysis on aggregated panels"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Tatsuki Onishi" }]
+keywords = ["change-point analysis", "aggregation", "synchrony", "panel time series", "calibration"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "numpy>=2.0,<2.4",
+    "scipy>=1.11",
+    "pandas>=2.0",
+    "statsmodels>=0.14",
+    "matplotlib>=3.8",
+    "joblib>=1.3",
+    "pyyaml>=6",
+    "scikit-learn>=1.5,<1.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/bougtoir/falsesync"
+Source = "https://github.com/bougtoir/falsesync"
+Issues = "https://github.com/bougtoir/falsesync/issues"
+Changelog = "https://github.com/bougtoir/falsesync/blob/main/CHANGELOG.md"
+DOI = "https://doi.org/10.5281/zenodo.23233536"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.5", "black>=24"]
+cp = ["ruptures>=1.1"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.black]
+line-length = 100

falsesync-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

falsesync-0.1.2/src/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-0.1.2/src/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-0.1.2/src/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()),
+    }