tpattern 0.1.4__tar.gz → 0.1.5__tar.gz

{tpattern-0.1.4/tpattern.egg-info → tpattern-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.4
+Version: 0.1.5
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
 License-Expression: MIT

{tpattern-0.1.4 → tpattern-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tpattern"
-version = "0.1.4"
+version = "0.1.5"
 description = "Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour"
 readme = "README.md"
 requires-python = ">=3.9"

tpattern-0.1.5/tests/test_null_compare.py

@@ -0,0 +1,64 @@
+"""compare_nulls: profile vs rotation decomposition into core and shell."""
+import os
+
+from tpattern import (Config, compare_nulls, NullComparison, calibrate,
+                      null_comparison_plot)
+from tpattern.synthetic import SyntheticSpec, make_dataset
+
+
+def _planted(frac=0.15, seed=7):
+    # a dataset with a genuine A->B coupling planted on top of background
+    obs, _ = make_dataset(SyntheticSpec(
+        n_seq=300, planted=[("A", 0), ("B", 1500)], plant_fraction=frac,
+        jitter=200, bg_rate=2.5, seed=seed))
+    return obs
+
+
+def test_compare_nulls_structure():
+    obs = _planted()
+    cfg = Config(min_lag=1)
+    cmp = compare_nulls(obs, cfg, nulls=("profile", "rotation"), B=100, seed=1)
+    assert isinstance(cmp, NullComparison)
+    assert set(cmp.nulls) == {"profile", "rotation"}
+    # detection is null-independent: both nulls see the same detected patterns
+    assert set(cmp.detected["profile"]) == set(cmp.detected["rotation"])
+    # core is exactly the intersection of the two survivor sets
+    assert cmp.common == cmp.survives["profile"] & cmp.survives["rotation"]
+    # unique sets are disjoint from the core and from each other
+    assert cmp.unique["profile"].isdisjoint(cmp.common)
+    assert cmp.unique["rotation"].isdisjoint(cmp.common)
+    assert cmp.unique["profile"].isdisjoint(cmp.unique["rotation"])
+
+
+def test_rows_and_layers_consistent():
+    obs = _planted()
+    cmp = compare_nulls(obs, Config(min_lag=1), B=100, seed=2)
+    for r in cmp.rows():
+        surv = [n for n in cmp.nulls if r["survives"][n]]
+        assert surv, "a row must survive at least one null"
+        if len(surv) == len(cmp.nulls):
+            assert r["layer"] == "core"
+        elif len(surv) == 1:
+            assert r["layer"] == f"{surv[0]}-only"
+        # every listed q is a probability
+        for n in cmp.nulls:
+            q = r["q"][n]
+            assert q is None or 0.0 <= q <= 1.0
+
+
+def test_matches_individual_calibrate():
+    # compare_nulls must agree with calling calibrate() per null
+    obs = _planted()
+    cfg = Config(min_lag=1)
+    cmp = compare_nulls(obs, cfg, nulls=("profile", "rotation"), B=100, seed=3)
+    for null in ("profile", "rotation"):
+        r = calibrate(obs, cfg, null=null, B=100, seed=3)
+        assert cmp.survives[null] == {c.pattern.signature() for c in r.kept("fdr")}
+
+
+def test_plot_writes_file(tmp_path):
+    obs = _planted()
+    cmp = compare_nulls(obs, Config(min_lag=1), B=100, seed=4)
+    out = tmp_path / "cmp.png"
+    null_comparison_plot(cmp, str(out), title="test")
+    assert out.exists() and out.stat().st_size > 0

{tpattern-0.1.4 → tpattern-0.1.5}/tpattern/__init__.py

@@ -6,16 +6,17 @@ behavior: T-patterns and their detection. Behavior Research Methods,
 Instruments, & Computers, 32(1), 93-110.
 """
 
-__version__ = "0.1.4"   # defined before submodule imports (methods.py reads it)
+__version__ = "0.1.5"   # defined before submodule imports (methods.py reads it)
 
 from .io import Observation, read_observation, read_sample, read_table
 from .pattern import Instance, Pattern
 from .ci import find_critical_interval, CIResult
 from .detect import Config, Engine
 from .randomise import run_null, NullResult, rotate, shuffle
-from .significance import calibrate, CalibrationResult
+from .significance import calibrate, CalibrationResult, compare_nulls, NullComparison
 from .report import patterns_table, forest_plot, report
-from .viz import pattern_dendrogram, patterns_overview, support_profile
+from .viz import (pattern_dendrogram, patterns_overview, support_profile,
+                  null_comparison_plot)
 from .advisor import recommend
 from .methods import methods_text
 from .guided import run_analysis, launch

{tpattern-0.1.4 → tpattern-0.1.5}/tpattern/advisor.py

@@ -109,7 +109,12 @@ def recommend(observations, *, min_count: int = 15,
                        f"(KS p<{uniformity_alpha}){ex_txt}, so the profile-preserving "
                        f"null (N2) was used to isolate cross-event coupling from each "
                        f"type's marginal timing; the rotation null (N1) is reported "
-                       f"alongside to quantify the marginal-timing contribution."),
+                       f"alongside to quantify the marginal-timing contribution. The "
+                       f"two nulls also pose different questions: N1 tests whether any "
+                       f"temporal structure is present, N2 whether events are coupled "
+                       f"beyond their own timing (the usual T-pattern claim), so N2 is "
+                       f"recommended here; choose N1 if your question is only whether "
+                       f"structure exists."),
             plain=("<b>Testing patterns against chance — without being fooled by "
                    "timing.</b> Some actions naturally tend to happen at particular "
                    "points (for example, shots come late in a move), so two actions can "

{tpattern-0.1.4 → tpattern-0.1.5}/tpattern/significance.py

@@ -224,3 +224,121 @@ def calibrate(observations, config: Config | None = None, *,
     return CalibrationResult(real=real, surrogate_counts=surrogate_counts,
                              B=B, alpha=alpha, q_target=q_target, null=null,
                              n_observations=len(observations))
+
+
+# ---- comparing nulls ---------------------------------------------------------
+
+@dataclass
+class NullComparison:
+    """Calibration of one sample under several surrogate nulls, and their difference.
+
+    The informative output is the DIFFERENCE between nulls, not either null alone.
+    With the profile and rotation nulls the surviving sets nest, and split into:
+
+      * the *core*  -- patterns surviving under every null: the coupling (sequence)
+        claim, genuine coordination beyond each event type's own timing;
+      * the *shell* -- patterns surviving the rotation null but not the profile null:
+        co-occurrence driven by shared timing (two types that inhabit the same phase
+        of play) rather than by coordination.
+
+    The shell is a finding in its own right, not noise: it answers "which actions
+    occupy the same moment?" while the core answers "which actions are chained?".
+    Build one with compare_nulls().
+    """
+    nulls: list
+    method: str
+    q_target: float
+    results: dict            # null -> CalibrationResult
+    detected: dict           # null -> {signature: Calibrated} (detection is null-independent)
+    survives: dict           # null -> set(signature) surviving the correction
+    common: set              # signatures surviving under ALL nulls (the core)
+    unique: dict             # null -> set(signature) surviving under that null alone
+
+    def _q(self, null, sig):
+        c = self.detected[null].get(sig)
+        return None if c is None else c.fdr_q
+
+    def _N(self, sig):
+        for d in self.detected.values():
+            if sig in d:
+                return d[sig].N
+        return None
+
+    def layer(self, sig):
+        """Which layer a surviving pattern occupies: 'core', '<null>-only', or a join."""
+        surv = tuple(n for n in self.nulls if sig in self.survives[n])
+        if len(surv) == len(self.nulls):
+            return "core"
+        if len(surv) == 1:
+            return f"{surv[0]}-only"
+        return "+".join(surv) if surv else "none"
+
+    def rows(self):
+        """One row per pattern surviving under at least one null, most significant first.
+
+        Each row: signature, N, layer, and per-null (survives, q). Tidy for a table.
+        """
+        anysurv = set().union(*self.survives.values()) if self.survives else set()
+        sigs = sorted(anysurv, key=lambda s: min((self._q(n, s) or 1.0) for n in self.nulls))
+        return [{
+            "signature": s,
+            "N": self._N(s),
+            "layer": self.layer(s),
+            "survives": {n: (s in self.survives[n]) for n in self.nulls},
+            "q": {n: self._q(n, s) for n in self.nulls},
+        } for s in sigs]
+
+    def summary(self):
+        """Short text summary that leads with the difference between nulls."""
+        pr = set(self.nulls) >= {"profile", "rotation"}
+        lines = [f"{n:10s}: {len(self.survives[n])} survive ({self.method.upper()} q<={self.q_target})"
+                 for n in self.nulls]
+        lines.append(f"core (survives all{', the coupling claim' if pr else ''}): {len(self.common)}")
+        for n in self.nulls:
+            if self.unique[n]:
+                tag = " (shared-timing shell)" if (n == "rotation" and "profile" in self.nulls) else ""
+                lines.append(f"{n}-only{tag}: {len(self.unique[n])}")
+        return "\n".join(lines)
+
+    def __str__(self):
+        head = f"Null comparison [{', '.join(self.nulls)}]"
+        tab = [f"  {'pattern':<50s} {'N':>4s}  "
+               + "  ".join(f"{n[:8]:>9s}" for n in self.nulls) + "  layer"]
+        for r in self.rows():
+            cells = "  ".join(
+                ((f"{r['q'][n]:.3f}" if r['q'][n] is not None else "  -  ")
+                 + ("*" if r['survives'][n] else " ")).rjust(9)
+                for n in self.nulls)
+            tab.append(f"  {r['signature'][:50]:<50s} {r['N']:>4d}  {cells}  {r['layer']}")
+        return (head + "\n" + self.summary() + "\n\n" + "\n".join(tab)
+                + "\n  (* = survives the correction; q shown per null)")
+
+
+def compare_nulls(observations, config=None, *, nulls=("profile", "rotation"),
+                  B=200, alpha=0.005, q_target=0.05, method="fdr", seed=20260714):
+    """Calibrate one sample under several nulls and decompose the survivors.
+
+    This is the 'both' option: it runs calibrate() once per null and reports, for
+    every pattern, which nulls it survives under, so the DIFFERENCE between nulls is
+    explicit. With the default profile-vs-rotation pair the result splits into a
+    coupling core (survives both) and a shared-timing shell (rotation-only); the
+    shell is a positive finding, not noise (see NullComparison).
+
+    Parameters mirror calibrate(); `nulls` is the tuple of nulls to compare and
+    `method` selects "fdr" or "fwer" for deciding survival. Detection is identical
+    across nulls, so only the calibration is repeated.
+
+    Returns a NullComparison: print it for a table, or use .rows()/.common/.unique.
+    """
+    config = config or Config()
+    nulls = list(nulls)
+    results = {n: calibrate(observations, config, null=n, B=B, alpha=alpha,
+                            q_target=q_target, seed=seed) for n in nulls}
+    detected = {n: {c.pattern.signature(): c for c in results[n].real} for n in nulls}
+    survives = {n: {c.pattern.signature() for c in results[n].kept(method)} for n in nulls}
+    common = set.intersection(*survives.values()) if survives else set()
+    unique = {n: survives[n] - set().union(*[survives[m] for m in nulls if m != n])
+              for n in nulls}
+    return NullComparison(nulls=nulls, method=method, q_target=q_target,
+                          results=results, detected=detected, survives=survives,
+                          common=common, unique=unique)

{tpattern-0.1.4 → tpattern-0.1.5}/tpattern/viz.py

@@ -219,3 +219,56 @@ def support_profile(result, outfile: str, title: str | None = None,
     fig.savefig(outfile)
     plt.close(fig)
     return [(sig, s) for sig, _, s in items]
+
+
+def null_comparison_plot(comparison, outfile, title=None, max_rows=25):
+    """Grid of which surrogate nulls each pattern survives, so the DIFFERENCE reads
+    at a glance. One row per pattern (surviving under at least one null), one column
+    per null; a filled cell means the pattern survives that null, annotated with its
+    q-value. Patterns are grouped core-first, then each null's unique (shell) set.
+
+    `comparison` is a NullComparison from compare_nulls(). Returns the rows plotted.
+    """
+    nulls = comparison.nulls
+    # order: core first, then each null's unique set, most significant within group
+    def _minq(sig):
+        return min((comparison._q(n, sig) or 1.0) for n in nulls)
+    ordered = ([s for s in sorted(comparison.common, key=_minq)]
+               + [s for n in nulls for s in sorted(comparison.unique[n], key=_minq)])
+    seen = set()
+    ordered = [s for s in ordered if not (s in seen or seen.add(s))][:max_rows]
+    if not ordered:
+        fig, ax = plt.subplots(figsize=(6, 2), dpi=200)
+        ax.text(0.5, 0.5, "No pattern survived under any null.", ha="center", va="center")
+        ax.axis("off"); fig.savefig(outfile); plt.close(fig); return []
+
+    GREEN, GREY, EDGE = "#2f7d4f", "#e4e7ec", "#333"
+    nrow, ncol = len(ordered), len(nulls)
+    fig, ax = plt.subplots(figsize=(3.0 + 1.5 * ncol, 1.1 + 0.42 * nrow), dpi=200)
+    for r, sig in enumerate(ordered):
+        y = nrow - 1 - r
+        layer = comparison.layer(sig)
+        for c, n in enumerate(nulls):
+            surv = sig in comparison.survives[n]
+            ax.add_patch(plt.Rectangle((c, y), 0.92, 0.92, facecolor=GREEN if surv else GREY,
+                                       edgecolor=EDGE, lw=0.6))
+            q = comparison._q(n, sig)
+            if q is not None:
+                ax.text(c + 0.46, y + 0.46, f"{q:.3f}", ha="center", va="center",
+                        fontsize=7.5, color="white" if surv else "#8a93a3",
+                        fontweight="bold" if surv else "normal")
+        ax.text(ncol + 0.15, y + 0.46, f"{sig}", ha="left", va="center", fontsize=7.4)
+        ax.text(-0.15, y + 0.46, layer, ha="right", va="center", fontsize=6.8,
+                color="#5b6270", style="italic")
+    ax.set_xlim(-2.4, ncol + 6.5); ax.set_ylim(-0.3, nrow + 0.2)
+    for c, n in enumerate(nulls):
+        ax.text(c + 0.46, nrow + 0.02, n, ha="center", va="bottom", fontsize=9, fontweight="bold")
+    ax.axis("off")
+    if title:
+        ax.set_title(title, fontsize=10.5, fontweight="bold", loc="left")
+    fig.text(0.5, 0.005, "filled = survives that null (q shown); core = survives all nulls, "
+             "shell = survives one null only", ha="center", fontsize=6.8, color="#8a93a3")
+    fig.tight_layout(rect=(0, 0.03, 1, 1))
+    fig.savefig(outfile)
+    plt.close(fig)
+    return ordered

{tpattern-0.1.4 → tpattern-0.1.5/tpattern.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.4
+Version: 0.1.5
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
 License-Expression: MIT

{tpattern-0.1.4 → tpattern-0.1.5}/tpattern.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ tests/test_calibrated_pins.py
 tests/test_contrast.py
 tests/test_dedup.py
 tests/test_guided.py
+tests/test_null_compare.py
 tests/test_reproduction.py
 tests/test_support_reporting.py
 tests/test_synthetic.py