systemictau-cancellation 0.1.0__tar.gz

systemictau_cancellation-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johel Padilla-Villanueva
+
+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.

systemictau_cancellation-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: systemictau-cancellation
+Version: 0.1.0
+Summary: Cancellation channel beside signed Systemic Tau: D = |mean change| + C
+Author-email: Johel Padilla-Villanueva <joel.padilla2@upr.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/johelpadilla/systemictau-cancellation
+Project-URL: Source, https://github.com/johelpadilla/systemictau-cancellation
+Project-URL: Note, https://doi.org/10.5281/zenodo.23073069
+Keywords: kendall-tau,systemic-tau,concordance,cancellation,time-series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: scipy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# systemictau-cancellation 0.1.0
+
+Canal de cancelación al lado de la media con signo de Tau Sistémico.
+
+La nota [10.5281/zenodo.23073069](https://doi.org/10.5281/zenodo.23073069) parte el cambio absoluto de las concordancias por pares:
+
+```text
+D = |Δ̄| + C,    κ = C / D
+```
+
+`Δ̄` es el cambio de la media con signo: el τ_s que ya devuelve `systemictau` 4.6.1. `C` es la parte que se cancela cuando unos pares ganan concordancia y otros la pierden. Este paquete calcula las dos piezas. No importa `systemictau` y no modifica la compuerta, el reloj `T_n`, `Protocol.frozen_v1` ni `nested-recd`.
+
+Instalación: `pip install systemictau-cancellation`.
+
+## Uso
+
+`X` tiene la misma forma que en `systemictau`: `(tiempo, módulos)`.
+
+```python
+from systemictau_cancellation import cancellation_channel, format_report
+
+out = cancellation_channel(X, window=13, n_cal=19, alpha=0.05)
+print(format_report(out))
+print(out.mode)      # calibration, quiet, coherent, cancellation, mixed
+print(out.tau_s)     # media con signo, tau-b
+print(out.D, out.C, out.kappa)
+```
+
+Las primeras `n_cal` ventanas son la línea base. El paso por defecto es igual a la ventana, así que los bloques no se solapan: esa es la disposición en la que la nota calibra el valor p. Con `alpha=0.05` hacen falta al menos 19 ventanas de calibración; si no, el valor p mínimo no alcanza 0.05.
+
+| Modo | Qué pasó en esa ventana |
+|---|---|
+| `coherent` | Se movió la media con signo |
+| `cancellation` | Se movió el cambio absoluto y la media con signo se quedó |
+| `mixed` | Las dos alarmas se encienden |
+| `quiet` | Ninguna alarma |
+| `calibration` | Ventana usada como línea base |
+
+Un desplazamiento grande y puro enciende las dos alarmas, porque ahí `D = |Δ̄|`. El modo queda `mixed`. La cancelación es el caso en el que `D` se enciende y la media no.
+
+## Cómo leer el modo
+
+`cancellation` dice que `D` salió de la calibración y la media con signo no. En la nota, ese patrón es el recableado balanceado. En un ciclo corto cuyos estados vecinos están más juntos que el ruido, el mismo patrón puede ser el ruido volteando rangos mientras el orden medio se sostiene. El modo no nombra la causa.
+
+El valor p es la calibración de la nota cuando los bloques son intercambiables y no se solapan. En una órbita continua las ventanas siguen siendo dependientes aunque el paso sea igual a la ventana, y el valor p queda descriptivo. Si el paso es menor que la ventana, `windows_overlap` es verdadero y el informe lo dice.
+
+## Qué τ se usa
+
+Cada ventana usa tau-b, el coseno de los vectores de signos, como la nota. El camino Numba de `systemictau` 4.6.1 usa tau-a. Sin empates los dos coinciden. `signed_tau_series(X, window=13)` devuelve la media con signo en el mismo índice temporal que `compute_taus`.
+
+## Reproducir las ilustraciones
+
+```bash
+python -m pytest -q
+python examples/demo_modes.py
+```
+
+La figura queda en `examples/modes_demo.png`. Esas series son un ejemplo corto. La Tabla 1 de la nota (semilla 20260930, 1000 ventanas) sigue viviendo en `cancellation-aware-tau` y no se regenera aquí.
+
+## Licencia
+
+MIT. Johel Padilla-Villanueva, ORCID 0000-0002-5797-6931.

systemictau_cancellation-0.1.0/README.md

@@ -0,0 +1,62 @@
+# systemictau-cancellation 0.1.0
+
+Canal de cancelación al lado de la media con signo de Tau Sistémico.
+
+La nota [10.5281/zenodo.23073069](https://doi.org/10.5281/zenodo.23073069) parte el cambio absoluto de las concordancias por pares:
+
+```text
+D = |Δ̄| + C,    κ = C / D
+```
+
+`Δ̄` es el cambio de la media con signo: el τ_s que ya devuelve `systemictau` 4.6.1. `C` es la parte que se cancela cuando unos pares ganan concordancia y otros la pierden. Este paquete calcula las dos piezas. No importa `systemictau` y no modifica la compuerta, el reloj `T_n`, `Protocol.frozen_v1` ni `nested-recd`.
+
+Instalación: `pip install systemictau-cancellation`.
+
+## Uso
+
+`X` tiene la misma forma que en `systemictau`: `(tiempo, módulos)`.
+
+```python
+from systemictau_cancellation import cancellation_channel, format_report
+
+out = cancellation_channel(X, window=13, n_cal=19, alpha=0.05)
+print(format_report(out))
+print(out.mode)      # calibration, quiet, coherent, cancellation, mixed
+print(out.tau_s)     # media con signo, tau-b
+print(out.D, out.C, out.kappa)
+```
+
+Las primeras `n_cal` ventanas son la línea base. El paso por defecto es igual a la ventana, así que los bloques no se solapan: esa es la disposición en la que la nota calibra el valor p. Con `alpha=0.05` hacen falta al menos 19 ventanas de calibración; si no, el valor p mínimo no alcanza 0.05.
+
+| Modo | Qué pasó en esa ventana |
+|---|---|
+| `coherent` | Se movió la media con signo |
+| `cancellation` | Se movió el cambio absoluto y la media con signo se quedó |
+| `mixed` | Las dos alarmas se encienden |
+| `quiet` | Ninguna alarma |
+| `calibration` | Ventana usada como línea base |
+
+Un desplazamiento grande y puro enciende las dos alarmas, porque ahí `D = |Δ̄|`. El modo queda `mixed`. La cancelación es el caso en el que `D` se enciende y la media no.
+
+## Cómo leer el modo
+
+`cancellation` dice que `D` salió de la calibración y la media con signo no. En la nota, ese patrón es el recableado balanceado. En un ciclo corto cuyos estados vecinos están más juntos que el ruido, el mismo patrón puede ser el ruido volteando rangos mientras el orden medio se sostiene. El modo no nombra la causa.
+
+El valor p es la calibración de la nota cuando los bloques son intercambiables y no se solapan. En una órbita continua las ventanas siguen siendo dependientes aunque el paso sea igual a la ventana, y el valor p queda descriptivo. Si el paso es menor que la ventana, `windows_overlap` es verdadero y el informe lo dice.
+
+## Qué τ se usa
+
+Cada ventana usa tau-b, el coseno de los vectores de signos, como la nota. El camino Numba de `systemictau` 4.6.1 usa tau-a. Sin empates los dos coinciden. `signed_tau_series(X, window=13)` devuelve la media con signo en el mismo índice temporal que `compute_taus`.
+
+## Reproducir las ilustraciones
+
+```bash
+python -m pytest -q
+python examples/demo_modes.py
+```
+
+La figura queda en `examples/modes_demo.png`. Esas series son un ejemplo corto. La Tabla 1 de la nota (semilla 20260930, 1000 ventanas) sigue viviendo en `cancellation-aware-tau` y no se regenera aquí.
+
+## Licencia
+
+MIT. Johel Padilla-Villanueva, ORCID 0000-0002-5797-6931.

systemictau_cancellation-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "systemictau-cancellation"
+version = "0.1.0"
+description = "Cancellation channel beside signed Systemic Tau: D = |mean change| + C"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Johel Padilla-Villanueva", email = "joel.padilla2@upr.edu"},
+]
+keywords = ["kendall-tau", "systemic-tau", "concordance", "cancellation", "time-series"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = ["numpy>=1.22"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "scipy>=1.10"]
+
+[project.urls]
+Homepage = "https://github.com/johelpadilla/systemictau-cancellation"
+Source = "https://github.com/johelpadilla/systemictau-cancellation"
+Note = "https://doi.org/10.5281/zenodo.23073069"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

systemictau_cancellation-0.1.0/setup.cfg

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

systemictau_cancellation-0.1.0/src/systemictau_cancellation/__init__.py

@@ -0,0 +1,30 @@
+"""Cancellation channel beside signed Systemic Tau.
+
+The published motor (systemictau 4.6.1) returns the signed mean. This
+package keeps that mean and adds the residual of the 2026-09-30 note:
+D = |mean change| + C.
+"""
+
+from .channel import (
+    NOTE_DOI,
+    ChannelResult,
+    cancellation_channel,
+    format_report,
+    minimum_calibration_windows,
+    signed_tau_series,
+)
+from .decomposition import decompose
+from .tau import tau_b_matrix
+
+__version__ = "0.1.0"
+__all__ = [
+    "NOTE_DOI",
+    "ChannelResult",
+    "cancellation_channel",
+    "decompose",
+    "format_report",
+    "minimum_calibration_windows",
+    "signed_tau_series",
+    "tau_b_matrix",
+    "__version__",
+]

systemictau_cancellation-0.1.0/src/systemictau_cancellation/channel.py

@@ -0,0 +1,257 @@
+"""Cancellation channel for a multivariate series.
+
+Input layout matches systemictau: X has shape (n_time, n_modules).
+The signed mean on each window is tau-b. D, C and kappa are measured
+against the mean of a calibration block of non-overlapping windows.
+
+Modes on a monitoring window:
+
+- coherent: the signed mean leaves the calibration range
+- cancellation: the absolute change leaves that range and the signed mean does not
+- mixed: both scores leave the range
+- quiet: neither score leaves the range
+
+The gate g(tau_s), the accumulated clock T_n and Protocol.frozen_v1 are
+left untouched. This module does not import them.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+from .decomposition import conformal_pvalue, conformal_scores, decompose, stat_D, stat_abs_mean
+from .tau import all_pairs, tau_b_matrix
+
+NOTE_DOI = "10.5281/zenodo.23073069"
+NOTE_RECORD = "https://doi.org/10.5281/zenodo.23073069"
+
+
+def minimum_calibration_windows(alpha: float) -> int:
+    """Smallest n_cal whose conformal p-value can fall at or under alpha."""
+    if not 0.0 < float(alpha) < 1.0:
+        raise ValueError("alpha must be strictly between 0 and 1")
+    return int(math.ceil(1.0 / float(alpha) - 1.0))
+
+
+@dataclass
+class ChannelResult:
+    """One row per window. Calibration rows leave the scores empty."""
+
+    window_end: np.ndarray
+    tau_s: np.ndarray
+    dbar: np.ndarray
+    D: np.ndarray
+    C: np.ndarray
+    kappa: np.ndarray
+    p_D: np.ndarray
+    p_signed: np.ndarray
+    mode: np.ndarray
+    undefined_fraction: np.ndarray
+    baseline: np.ndarray
+    pairs: np.ndarray
+    alpha: float
+    n_cal: int
+    window: int
+    stride: int
+    windows_overlap: bool
+    note_doi: str = NOTE_DOI
+
+    def monitoring_mask(self) -> np.ndarray:
+        return self.mode != "calibration"
+
+    def summary(self) -> dict:
+        mon = self.monitoring_mask()
+        modes, counts = np.unique(self.mode[mon], return_counts=True)
+        return {
+            "n_monitoring": int(mon.sum()),
+            "mean_abs_dbar": float(np.mean(np.abs(self.dbar[mon]))) if mon.any() else float("nan"),
+            "mean_D": float(np.mean(self.D[mon])) if mon.any() else float("nan"),
+            "mean_kappa": float(np.nanmean(self.kappa[mon])) if mon.any() else float("nan"),
+            "modes": {str(k): int(v) for k, v in zip(modes, counts)},
+        }
+
+
+def format_report(result: ChannelResult) -> str:
+    """Spanish one-screen summary of a channel result."""
+    s = result.summary()
+    modes = ", ".join(f"{k}: {v}" for k, v in sorted(s["modes"].items()))
+    overlap = ""
+    if result.windows_overlap:
+        overlap = (
+            "\nLas ventanas se solapan. El valor p describe el puntaje; "
+            "la nota calibra ventanas no solapadas."
+        )
+    return (
+        f"Canal de cancelación (nota {result.note_doi})\n"
+        f"ventana={result.window}  paso={result.stride}  "
+        f"calibración={result.n_cal}  alpha={result.alpha}\n"
+        f"ventanas de monitoreo: {s['n_monitoring']}\n"
+        f"media |Δ̄| = {s['mean_abs_dbar']:.4f}\n"
+        f"media D    = {s['mean_D']:.4f}\n"
+        f"media κ    = {s['mean_kappa']:.4f}\n"
+        f"modos: {modes}"
+        f"{overlap}"
+    )
+
+
+def _as_series(X: np.ndarray) -> np.ndarray:
+    X = np.asarray(X, dtype=float)
+    if X.ndim != 2:
+        raise ValueError("X must have shape (n_time, n_modules)")
+    if X.shape[1] < 2:
+        raise ValueError("at least two modules are required")
+    if not np.isfinite(X).all():
+        raise ValueError("X contains a non-finite value")
+    return X
+
+
+def _pairs_of(n_modules: int, pairs) -> np.ndarray:
+    if pairs is None:
+        return all_pairs(n_modules)
+    out = np.asarray(pairs, dtype=int)
+    if out.ndim != 2 or out.shape[1] != 2 or out.shape[0] == 0:
+        raise ValueError("pairs must have shape (n_pairs, 2)")
+    if out.min() < 0 or out.max() >= n_modules:
+        raise ValueError("a pair index is outside the module range")
+    if np.any(out[:, 0] == out[:, 1]):
+        raise ValueError("a pair repeats the same module")
+    return out
+
+
+def _window_ends(n_time: int, window: int, stride: int) -> np.ndarray:
+    if window < 2:
+        raise ValueError("window must be at least 2")
+    if stride < 1:
+        raise ValueError("stride must be at least 1")
+    if n_time < window:
+        raise ValueError("the series is shorter than one window")
+    return np.arange(window - 1, n_time, stride, dtype=int)
+
+
+def _pair_rows(X: np.ndarray, window: int, stride: int, pairs: np.ndarray):
+    ends = _window_ends(X.shape[0], window, stride)
+    n = len(ends)
+    m = pairs.shape[0]
+    values = np.empty((n, m), dtype=float)
+    undefined = np.empty(n, dtype=float)
+    left = pairs[:, 0]
+    right = pairs[:, 1]
+    for k, end in enumerate(ends):
+        block = X[end - window + 1:end + 1].T
+        tau, defined = tau_b_matrix(block)
+        values[k] = tau[left, right]
+        undefined[k] = 1.0 - float(defined[left, right].mean())
+    return ends, values, undefined
+
+
+def signed_tau_series(X: np.ndarray, window: int = 13, stride: int = 1, pairs=None) -> np.ndarray:
+    """Signed mean of pairwise tau-b, indexed like systemictau.compute_taus.
+
+    The value sits at the last time index of each window. Earlier positions,
+    and positions skipped by the stride, are nan.
+    """
+    X = _as_series(X)
+    chosen = _pairs_of(X.shape[1], pairs)
+    ends, values, _ = _pair_rows(X, int(window), int(stride), chosen)
+    taus = np.full(X.shape[0], np.nan)
+    taus[ends] = values.mean(axis=1)
+    return taus
+
+
+def _mode(p_D: float, p_signed: float, alpha: float) -> str:
+    hit_D = p_D <= alpha
+    hit_signed = p_signed <= alpha
+    if hit_signed and hit_D:
+        return "mixed"
+    if hit_signed:
+        return "coherent"
+    if hit_D:
+        return "cancellation"
+    return "quiet"
+
+
+def cancellation_channel(
+    X: np.ndarray,
+    window: int = 13,
+    stride: int | None = None,
+    n_cal: int = 19,
+    alpha: float = 0.05,
+    pairs=None,
+) -> ChannelResult:
+    """Baseline the first n_cal windows and label every later window.
+
+    The default stride equals the window, so the blocks do not overlap.
+    That is the layout in which the note calibrates the conformal p-value,
+    and the calibration applies when those blocks are exchangeable.
+    On a continuous orbit the windows stay serially dependent even when they
+    do not overlap, so the p-value is descriptive. A smaller stride is
+    accepted; ChannelResult.windows_overlap is then true and the report says so.
+
+    A mode of ``cancellation`` means D left the calibration range and the
+    signed mean did not. On a short cycle this can be noise flipping ranks.
+    """
+    X = _as_series(X)
+    window = int(window)
+    if stride is None:
+        stride = window
+    stride = int(stride)
+    n_cal = int(n_cal)
+    alpha = float(alpha)
+    need = minimum_calibration_windows(alpha)
+    if n_cal < need:
+        raise ValueError(
+            f"n_cal={n_cal} cannot reach alpha={alpha}. "
+            f"Use at least {need} calibration windows."
+        )
+    chosen = _pairs_of(X.shape[1], pairs)
+    ends, values, undefined = _pair_rows(X, window, stride, chosen)
+    if len(ends) <= n_cal:
+        raise ValueError(
+            f"the series yields {len(ends)} windows and n_cal={n_cal}. "
+            "One monitoring window is required."
+        )
+
+    n = len(ends)
+    dbar = np.full(n, np.nan)
+    D = np.full(n, np.nan)
+    C = np.full(n, np.nan)
+    kappa = np.full(n, np.nan)
+    p_D = np.full(n, np.nan)
+    p_signed = np.full(n, np.nan)
+    mode = np.full(n, "calibration", dtype="<U12")
+    cal = values[:n_cal]
+    baseline = cal.mean(axis=0)
+
+    for k in range(n_cal, n):
+        part = decompose(values[k] - baseline)
+        scores_D, new_D = conformal_scores(cal, values[k], stat_D)
+        scores_s, new_s = conformal_scores(cal, values[k], stat_abs_mean)
+        dbar[k] = part["dbar"]
+        D[k] = part["D"]
+        C[k] = part["C"]
+        kappa[k] = part["kappa"]
+        p_D[k] = conformal_pvalue(scores_D, new_D)
+        p_signed[k] = conformal_pvalue(scores_s, new_s)
+        mode[k] = _mode(p_D[k], p_signed[k], alpha)
+
+    return ChannelResult(
+        window_end=ends,
+        tau_s=values.mean(axis=1),
+        dbar=dbar,
+        D=D,
+        C=C,
+        kappa=kappa,
+        p_D=p_D,
+        p_signed=p_signed,
+        mode=mode,
+        undefined_fraction=undefined,
+        baseline=baseline,
+        pairs=chosen,
+        alpha=alpha,
+        n_cal=n_cal,
+        window=window,
+        stride=stride,
+        windows_overlap=stride < window,
+    )

systemictau_cancellation-0.1.0/src/systemictau_cancellation/decomposition.py

@@ -0,0 +1,71 @@
+"""Exact split of a vector of pairwise changes.
+
+    D = |mean(delta)| + C
+    kappa = C / D
+
+C is the absolute change cancelled by opposite signs. The identity is the
+one proved and checked in Padilla-Villanueva (2026),
+https://doi.org/10.5281/zenodo.23073069.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def decompose(delta: np.ndarray) -> dict:
+    """Split one vector of edge changes into signed mean, D, C and kappa."""
+    d = np.asarray(delta, dtype=float).ravel()
+    m = int(d.size)
+    if m == 0:
+        raise ValueError("empty edge set")
+    s_plus = float(d[d > 0].sum())
+    s_minus = float((-d[d < 0]).sum())
+    D = float(np.abs(d).mean())
+    dbar = float(d.mean())
+    C = D - abs(dbar)
+    if dbar > 0:
+        minority = s_minus
+    elif dbar < 0:
+        minority = s_plus
+    else:
+        minority = s_plus
+    C_min = 2.0 * minority / m
+    kappa = C / D if D > 0 else float("nan")
+    return {
+        "D": D,
+        "dbar": dbar,
+        "abs_dbar": abs(dbar),
+        "C": C,
+        "C_minority": C_min,
+        "kappa": kappa,
+        "S_plus": s_plus,
+        "S_minus": s_minus,
+        "argmax": int(np.argmax(np.abs(d))),
+    }
+
+
+def stat_D(delta: np.ndarray) -> float:
+    return float(np.mean(np.abs(np.asarray(delta, dtype=float))))
+
+
+def stat_abs_mean(delta: np.ndarray) -> float:
+    return float(abs(np.mean(np.asarray(delta, dtype=float))))
+
+
+def conformal_scores(cal: np.ndarray, new: np.ndarray, stat) -> tuple[np.ndarray, float]:
+    """Full-conformal scores. Calibration scores depend on the new window.
+
+    For the monitored window the baseline is the mean of the calibration
+    windows. Same construction as the technical note.
+    """
+    allw = np.vstack([np.asarray(cal, dtype=float), np.asarray(new, dtype=float)[None, :]])
+    n1 = allw.shape[0]
+    total = allw.sum(axis=0)
+    base = (total[None, :] - allw) / (n1 - 1)
+    scores = np.array([stat(allw[k] - base[k]) for k in range(n1)], dtype=float)
+    return scores[:-1], float(scores[-1])
+
+
+def conformal_pvalue(cal_scores: np.ndarray, new_score: float) -> float:
+    cal_scores = np.asarray(cal_scores, dtype=float)
+    return float((1.0 + np.sum(cal_scores >= new_score)) / (len(cal_scores) + 1.0))

systemictau_cancellation-0.1.0/src/systemictau_cancellation/synthetic.py

@@ -0,0 +1,56 @@
+"""Small series with a known order pattern.
+
+These are illustrations for the channel. They are not the Monte Carlo of
+the technical note (seed 20260930, 1000 windows).
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def _independent(n_windows: int, window: int, n_modules: int, rng) -> np.ndarray:
+    return rng.normal(size=(n_windows, window, n_modules))
+
+
+def _ordered(window: int, n_modules: int, reversed_modules: tuple[int, ...]) -> np.ndarray:
+    ticks = np.arange(window, dtype=float)
+    block = np.tile(ticks[:, None], (1, n_modules))
+    for j in reversed_modules:
+        block[:, j] = ticks[::-1]
+    return block
+
+
+def stack_windows(blocks: np.ndarray) -> np.ndarray:
+    """(n_windows, window, n_modules) -> (n_time, n_modules)."""
+    n_windows, window, n_modules = blocks.shape
+    return np.ascontiguousarray(blocks.reshape(n_windows * window, n_modules))
+
+
+def quiet_series(n_cal: int, n_mon: int, window: int, n_modules: int, seed: int) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    blocks = _independent(n_cal + n_mon, window, n_modules, rng)
+    return stack_windows(blocks)
+
+
+def coherent_series(n_cal: int, n_mon: int, window: int, n_modules: int, seed: int) -> np.ndarray:
+    """Calibration is independent noise. Monitoring windows share one order."""
+    rng = np.random.default_rng(seed)
+    cal = _independent(n_cal, window, n_modules, rng)
+    mono = _ordered(window, n_modules, ())
+    mon = np.broadcast_to(mono, (n_mon, window, n_modules)).copy()
+    return stack_windows(np.concatenate([cal, mon], axis=0))
+
+
+def cancellation_series(n_cal: int, n_mon: int, window: int, seed: int) -> np.ndarray:
+    """Four modules. Monitoring taus are +1,+1,+1,-1,-1,-1.
+
+    Modules 0, 1 and 3 rise together. Module 2 is the reverse order.
+    The signed mean of the six pairs is 0. Every pair is at ±1, so the
+    absolute change is large when the calibration baseline is near 0.
+    """
+    rng = np.random.default_rng(seed)
+    n_modules = 4
+    cal = _independent(n_cal, window, n_modules, rng)
+    mono = _ordered(window, n_modules, (2,))
+    mon = np.broadcast_to(mono, (n_mon, window, n_modules)).copy()
+    return stack_windows(np.concatenate([cal, mon], axis=0))

systemictau_cancellation-0.1.0/src/systemictau_cancellation/tau.py

@@ -0,0 +1,47 @@
+"""Kendall tau-b on one window.
+
+Same definition as the technical note
+*Cancellation-aware order coherence* (Padilla-Villanueva, 2026;
+https://doi.org/10.5281/zenodo.23073069): tau-b is the cosine of the
+pairwise sign vectors. A constant stream has an undefined coefficient;
+it is stored as 0 and marked in the definedness mask.
+
+This is tau-b. The Numba path of systemictau 4.6.1 divides by n(n-1)/2
+and is tau-a. The two agree when the window has no ties.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import numpy as np
+
+
+@lru_cache(maxsize=16)
+def _pair_index(n_bins: int):
+    return np.triu_indices(int(n_bins), 1)
+
+
+def sign_vectors(Z: np.ndarray) -> np.ndarray:
+    """Sign of every within-stream comparison. Z has shape (n_modules, n_bins)."""
+    Z = np.asarray(Z, dtype=float)
+    k, l = _pair_index(Z.shape[1])
+    return np.sign(Z[:, l] - Z[:, k])
+
+
+def tau_b_matrix(Z: np.ndarray):
+    """Return (tau, defined) for one window. Z has shape (n_modules, n_bins)."""
+    S = sign_vectors(Z)
+    G = S @ S.T
+    nrm = np.sqrt(np.clip(np.diag(G), 0.0, None))
+    den = np.outer(nrm, nrm)
+    defined = den > 0
+    T = np.zeros_like(G, dtype=float)
+    np.divide(G, den, out=T, where=defined)
+    np.fill_diagonal(T, 1.0)
+    return T, defined
+
+
+def all_pairs(n_modules: int) -> np.ndarray:
+    """Upper-triangle pairs as an array of shape (n_pairs, 2)."""
+    i, j = np.triu_indices(int(n_modules), 1)
+    return np.column_stack((i, j))

systemictau_cancellation-0.1.0/src/systemictau_cancellation.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: systemictau-cancellation
+Version: 0.1.0
+Summary: Cancellation channel beside signed Systemic Tau: D = |mean change| + C
+Author-email: Johel Padilla-Villanueva <joel.padilla2@upr.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/johelpadilla/systemictau-cancellation
+Project-URL: Source, https://github.com/johelpadilla/systemictau-cancellation
+Project-URL: Note, https://doi.org/10.5281/zenodo.23073069
+Keywords: kendall-tau,systemic-tau,concordance,cancellation,time-series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: scipy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# systemictau-cancellation 0.1.0
+
+Canal de cancelación al lado de la media con signo de Tau Sistémico.
+
+La nota [10.5281/zenodo.23073069](https://doi.org/10.5281/zenodo.23073069) parte el cambio absoluto de las concordancias por pares:
+
+```text
+D = |Δ̄| + C,    κ = C / D
+```
+
+`Δ̄` es el cambio de la media con signo: el τ_s que ya devuelve `systemictau` 4.6.1. `C` es la parte que se cancela cuando unos pares ganan concordancia y otros la pierden. Este paquete calcula las dos piezas. No importa `systemictau` y no modifica la compuerta, el reloj `T_n`, `Protocol.frozen_v1` ni `nested-recd`.
+
+Instalación: `pip install systemictau-cancellation`.
+
+## Uso
+
+`X` tiene la misma forma que en `systemictau`: `(tiempo, módulos)`.
+
+```python
+from systemictau_cancellation import cancellation_channel, format_report
+
+out = cancellation_channel(X, window=13, n_cal=19, alpha=0.05)
+print(format_report(out))
+print(out.mode)      # calibration, quiet, coherent, cancellation, mixed
+print(out.tau_s)     # media con signo, tau-b
+print(out.D, out.C, out.kappa)
+```
+
+Las primeras `n_cal` ventanas son la línea base. El paso por defecto es igual a la ventana, así que los bloques no se solapan: esa es la disposición en la que la nota calibra el valor p. Con `alpha=0.05` hacen falta al menos 19 ventanas de calibración; si no, el valor p mínimo no alcanza 0.05.
+
+| Modo | Qué pasó en esa ventana |
+|---|---|
+| `coherent` | Se movió la media con signo |
+| `cancellation` | Se movió el cambio absoluto y la media con signo se quedó |
+| `mixed` | Las dos alarmas se encienden |
+| `quiet` | Ninguna alarma |
+| `calibration` | Ventana usada como línea base |
+
+Un desplazamiento grande y puro enciende las dos alarmas, porque ahí `D = |Δ̄|`. El modo queda `mixed`. La cancelación es el caso en el que `D` se enciende y la media no.
+
+## Cómo leer el modo
+
+`cancellation` dice que `D` salió de la calibración y la media con signo no. En la nota, ese patrón es el recableado balanceado. En un ciclo corto cuyos estados vecinos están más juntos que el ruido, el mismo patrón puede ser el ruido volteando rangos mientras el orden medio se sostiene. El modo no nombra la causa.
+
+El valor p es la calibración de la nota cuando los bloques son intercambiables y no se solapan. En una órbita continua las ventanas siguen siendo dependientes aunque el paso sea igual a la ventana, y el valor p queda descriptivo. Si el paso es menor que la ventana, `windows_overlap` es verdadero y el informe lo dice.
+
+## Qué τ se usa
+
+Cada ventana usa tau-b, el coseno de los vectores de signos, como la nota. El camino Numba de `systemictau` 4.6.1 usa tau-a. Sin empates los dos coinciden. `signed_tau_series(X, window=13)` devuelve la media con signo en el mismo índice temporal que `compute_taus`.
+
+## Reproducir las ilustraciones
+
+```bash
+python -m pytest -q
+python examples/demo_modes.py
+```
+
+La figura queda en `examples/modes_demo.png`. Esas series son un ejemplo corto. La Tabla 1 de la nota (semilla 20260930, 1000 ventanas) sigue viviendo en `cancellation-aware-tau` y no se regenera aquí.
+
+## Licencia
+
+MIT. Johel Padilla-Villanueva, ORCID 0000-0002-5797-6931.

systemictau_cancellation-0.1.0/src/systemictau_cancellation.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/systemictau_cancellation/__init__.py
+src/systemictau_cancellation/channel.py
+src/systemictau_cancellation/decomposition.py
+src/systemictau_cancellation/synthetic.py
+src/systemictau_cancellation/tau.py
+src/systemictau_cancellation.egg-info/PKG-INFO
+src/systemictau_cancellation.egg-info/SOURCES.txt
+src/systemictau_cancellation.egg-info/dependency_links.txt
+src/systemictau_cancellation.egg-info/requires.txt
+src/systemictau_cancellation.egg-info/top_level.txt
+tests/test_channel.py

systemictau_cancellation-0.1.0/src/systemictau_cancellation.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

systemictau_cancellation-0.1.0/src/systemictau_cancellation.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy>=1.22
+
+[dev]
+pytest>=7.0
+scipy>=1.10

systemictau_cancellation-0.1.0/src/systemictau_cancellation.egg-info/top_level.txt

@@ -0,0 +1 @@
+systemictau_cancellation

systemictau_cancellation-0.1.0/tests/test_channel.py

@@ -0,0 +1,120 @@
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from systemictau_cancellation import (
+    cancellation_channel,
+    decompose,
+    signed_tau_series,
+    tau_b_matrix,
+)
+from systemictau_cancellation.synthetic import (
+    cancellation_series,
+    coherent_series,
+    quiet_series,
+)
+
+
+def test_identity_on_random_changes():
+    rng = np.random.default_rng(1)
+    for _ in range(2000):
+        d = rng.normal(size=int(rng.integers(2, 40)))
+        r = decompose(d)
+        assert r["D"] == pytest.approx(r["abs_dbar"] + r["C"], abs=1e-12)
+        assert r["C"] == pytest.approx(r["C_minority"], abs=1e-12)
+        if r["D"] > 0:
+            assert r["kappa"] == pytest.approx(1.0 - r["abs_dbar"] / r["D"], abs=1e-12)
+
+
+def test_kappa_extremes():
+    assert decompose(np.array([0.1, 0.3, 0.0, 0.2]))["kappa"] == pytest.approx(0.0)
+    assert decompose(np.array([0.1, -0.1, 0.4, -0.4]))["kappa"] == pytest.approx(1.0)
+
+
+def test_channel_identity_and_index():
+    X = quiet_series(n_cal=19, n_mon=6, window=12, n_modules=4, seed=2)
+    out = cancellation_channel(X, window=12, n_cal=19)
+    mon = out.monitoring_mask()
+    assert np.allclose(out.D[mon], np.abs(out.dbar[mon]) + out.C[mon])
+    assert out.mode[:19].tolist() == ["calibration"] * 19
+    assert out.window_end[0] == 11
+    assert out.windows_overlap is False
+    series = signed_tau_series(X, window=12, stride=12)
+    assert series[out.window_end] == pytest.approx(out.tau_s)
+
+
+def test_coherent_series_moves_the_signed_mean():
+    X = coherent_series(n_cal=19, n_mon=4, window=12, n_modules=4, seed=3)
+    out = cancellation_channel(X, window=12, n_cal=19)
+    mon = out.monitoring_mask()
+    assert set(out.mode[mon]).issubset({"coherent", "mixed"})
+    assert float(np.mean(out.dbar[mon])) > 0.7
+    assert float(np.nanmean(out.kappa[mon])) < 0.15
+
+
+def test_balanced_reversal_is_cancellation():
+    X = cancellation_series(n_cal=19, n_mon=4, window=12, seed=4)
+    out = cancellation_channel(X, window=12, n_cal=19)
+    mon = out.monitoring_mask()
+    assert set(out.mode[mon]) == {"cancellation"}
+    assert abs(float(np.mean(out.dbar[mon]))) < 0.15
+    assert float(np.nanmean(out.kappa[mon])) > 0.85
+    assert float(np.mean(out.D[mon])) > 0.7
+
+
+def test_quiet_series_rarely_alarms():
+    X = quiet_series(n_cal=19, n_mon=40, window=10, n_modules=3, seed=5)
+    out = cancellation_channel(X, window=10, n_cal=19)
+    mon = out.mode[out.monitoring_mask()]
+    alarmed = np.isin(mon, ["coherent", "cancellation", "mixed"]).mean()
+    assert alarmed < 0.25
+
+
+def test_short_calibration_is_refused():
+    X = quiet_series(n_cal=5, n_mon=2, window=8, n_modules=3, seed=6)
+    with pytest.raises(ValueError, match="n_cal"):
+        cancellation_channel(X, window=8, n_cal=5, alpha=0.05)
+
+
+def test_tau_b_matches_scipy_when_present():
+    scipy_stats = pytest.importorskip("scipy.stats")
+    rng = np.random.default_rng(7)
+    Z = rng.poisson(0.8, size=(4, 30)).astype(float)
+    T, defined = tau_b_matrix(Z)
+    for i, j in [(0, 1), (0, 2), (1, 3)]:
+        if defined[i, j]:
+            ref = scipy_stats.kendalltau(Z[i], Z[j], variant="b").statistic
+            assert T[i, j] == pytest.approx(ref, abs=1e-12)
+
+
+def test_matches_published_note_code():
+    note = Path("/Users/johelpadilla/grok-safe/cancellation-aware-tau/code")
+    if not (note / "cancellation_tau" / "decomposition.py").is_file():
+        pytest.skip("local note tree is absent")
+    sys.path.insert(0, str(note))
+    from cancellation_tau import decompose as note_decompose
+    from cancellation_tau import tau_b_matrix as note_tau
+    from cancellation_tau.calibration import conformal_pvalue as note_p
+    from cancellation_tau.calibration import conformal_scores as note_scores
+    from cancellation_tau.calibration import stat_D as note_stat_D
+    from systemictau_cancellation.decomposition import conformal_pvalue, conformal_scores, stat_D
+
+    rng = np.random.default_rng(20260930)
+    Z = rng.poisson(0.8, size=(5, 30)).astype(float)
+    got, got_defined = tau_b_matrix(Z)
+    ref, ref_defined = note_tau(Z)
+    assert np.allclose(got, ref)
+    assert np.array_equal(got_defined, ref_defined)
+    delta = rng.normal(size=15)
+    a, b = decompose(delta), note_decompose(delta)
+    for key in ("D", "dbar", "C", "kappa", "C_minority"):
+        assert a[key] == pytest.approx(b[key], abs=1e-12)
+    cal = rng.normal(size=(19, 6))
+    new = rng.normal(size=6)
+    got_scores, got_new = conformal_scores(cal, new, stat_D)
+    ref_scores, ref_new = note_scores(cal, new, note_stat_D)
+    assert got_scores == pytest.approx(ref_scores, abs=1e-12)
+    assert got_new == pytest.approx(ref_new, abs=1e-12)
+    assert conformal_pvalue(got_scores, got_new) == pytest.approx(note_p(ref_scores, ref_new))