tpattern 0.1.0__tar.gz

tpattern-0.1.0/LICENSE

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

tpattern-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: tpattern
+Version: 0.1.0
+Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
+Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
+License: MIT
+Project-URL: Homepage, https://github.com/ajcallaway/TPattern
+Project-URL: Repository, https://github.com/ajcallaway/TPattern
+Project-URL: Archive (DOI), https://doi.org/10.5281/zenodo.21397543
+Project-URL: Tagging tool (OpenTag), https://opentag.studio
+Keywords: t-pattern,THEME,temporal,sequence,sport,behaviour,notation analysis
+Classifier: Development Status :: 4 - Beta
+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: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+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.21
+Requires-Dist: scipy>=1.7
+Requires-Dist: matplotlib>=3.4
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Provides-Extra: gui
+Requires-Dist: ipywidgets>=8; extra == "gui"
+Requires-Dist: pandas>=1.3; extra == "gui"
+Requires-Dist: openpyxl>=3; extra == "gui"
+Dynamic: license-file
+
+# tpattern — open, auditable analysis of recurring patterns in event sequences
+
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ajcallaway/TPattern/blob/main/colab/tpattern_guided_analysis.ipynb)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21397543.svg)](https://doi.org/10.5281/zenodo.21397543)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`tpattern` detects recurring temporal patterns (T-patterns; Magnusson, 2000) in
+**any sequence of timed, labelled events** — behaviour, sport, clinical or
+physiological logs, interaction data — validates them properly against chance, and
+produces clean, publication-ready output (tables, figures, pattern dendrograms). It
+is a free, transparent, reproducible alternative to the THEME software, and the
+analysis companion to the [OpenTag.Studio](https://opentag.studio) tagging tool.
+
+## Two ways to use it
+
+- 🚀 **Google Colab — no coding.** [**Open the guided notebook in Colab**](https://colab.research.google.com/github/ajcallaway/TPattern/blob/main/colab/tpattern_guided_analysis.ipynb): upload your events, follow the guided steps, download a report with a plain-English verdict for every pattern and a paste-ready Methods paragraph. See [`colab/`](colab/).
+- 🐍 **Python library.** `pip install` and script it — see [Quickstart](#quickstart) and [`examples/`](examples/).
+
+Bring your own data (one row per event — see [`SCHEMA.md`](SCHEMA.md)) or try the
+included [`data/`](data/) example.
+
+## Why it exists
+
+T-pattern analysis finds behaviourally meaningful structure that event counts and 
+simple transition tables miss. It is most established through Magnusson's THEME
+software, the reference implementation. `tpattern` is an open, complementary
+implementation that reproduces THEME's detection and adds a reproducible chance
+model and clear reporting:
+
+- **reproduces** THEME's core detection (critical intervals, Nx/T baseline,
+  completeness competition) — validated to the pattern for published datasets;
+- **adds a chance model** — every pattern is tested against a surrogate null, with
+  p-values **corrected for repeated testing** (false-discovery rate and
+  family-wise);
+- **handles concurrency explicitly** — events sharing a timestamp are treated as
+  co-occurrence rather than sequence;
+- **reports clearly** — tidy tables, effect sizes with confidence intervals,
+  purposeful figures, and clean **dendrograms** of the detected patterns.
+
+## Installation
+
+From source (until published on PyPI):
+
+```bash
+git clone https://github.com/ajcallaway/TPattern.git
+cd tpattern
+pip install -e .
+```
+
+Requires Python ≥ 3.9 (depends on numpy, scipy, matplotlib).
+
+## Quickstart
+
+```python
+from tpattern import read_table, Config, recommend, calibrate, report, methods_text
+
+# 1. Load your events — one row per event (observation, event, start).
+#    Pass time_unit="ms" if your times are in milliseconds (default is seconds).
+#    See SCHEMA.md for the (simple) required format.
+observations = read_table("events.csv", time_unit="s")
+
+# 2. Let the tool inspect the data and recommend the method — which surrogate
+#    null, whether to require a genuine lag, which error control — with reasons.
+print(recommend(observations))
+
+# 3. Detect and calibrate in one call: every pattern is tested against a
+#    surrogate null with correction for repeated testing.
+#    (calibrate() runs the detection for you — you don't call detect() first.)
+result = calibrate(observations, Config(), null="profile", B=200, q_target=0.05)
+survivors = result.kept("fdr")     # patterns that survive false-discovery control
+
+# 4. Report: a tidy table (with q-values), pattern dendrograms and a summary —
+#    plus a paste-ready Methods paragraph stating every setting and what it does.
+report(result, "report_out", title="My analysis")
+print(methods_text(Config(), observations=observations, calibration=result))
+```
+
+Two runnable examples:
+
+```bash
+pip install -e .
+python examples/quickstart.py          # no data needed (synthetic ground-truth demo)
+python examples/reproduce_worldcup.py  # a real read_table + full analysis on shipped data
+```
+
+Just want the detected patterns without calibration? `Engine(observations,
+Config()).detect()` returns them directly.
+
+**Comparing two groups** (winner vs loser, goal vs non-goal, condition A vs B)?
+`group_contrast(observations, group_of)` tests each pattern's occurrence between
+the groups (Fisher's exact test, odds ratio + 95% CI) and feeds `forest_plot`.
+
+## The workflow
+
+```
+   tag events            export             analyse                    report
+ (OpenTag / Sportscode) ──────▶ standard ──▶ tpattern ──▶ tables · figures · dendrograms
+                                 table         (detect · validate ·
+                                               calibrate)
+```
+
+1. **Tag** your video/events in any coding tool.
+2. **Export** to the standard input structure — one row per event
+   (`observation, event, start`, plus optional `end`, descriptor and group
+   columns). See [`SCHEMA.md`](SCHEMA.md).
+3. **Set up your coding** so the export is analysis-ready — one event per action,
+   explicit outcomes, unit boundaries. See [`CODING_GUIDE.md`](CODING_GUIDE.md).
+4. **Detect** T-patterns, **validate** them against a surrogate null with corrected
+   significance (`recommend` advises the settings; `calibrate` runs it), and
+   **report** (tables, dendrograms, and a `methods_text` Methods paragraph).
+
+## Relationship to OpenTag.Studio
+
+[OpenTag.Studio](https://opentag.studio) is a free, browser-based sports video
+tagging tool. It is the natural front end for `tpattern`: tag your footage, export
+a session, and analyse it here — no proprietary software anywhere in the pipeline.
+OpenTag's **THEME & GSEQ setup guide** covers how to design a coding window so the
+export is analysis-ready, and that guidance applies directly to `tpattern`
+(`CODING_GUIDE.md` is the short bridge). Together they form a complete, open
+tag → analysis pipeline.
+
+## Reproducing the published results
+
+The derived 2022 World Cup event sequences ship in [`data/`](data/), so the
+published analyses reproduce from this repository alone:
+
+```bash
+python examples/reproduce_worldcup.py              # concordance, exclusion, concurrency (~5 s)
+python examples/reproduce_worldcup.py --calibrate  # also the surrogate null (~10 min)
+```
+
+This regenerates the tpattern-vs-THEME pattern counts by level, the interception
+exclusion divergence, the co-occurrence-vs-sequence analysis, and how many patterns
+survive the surrogate null. All seeded and deterministic. See
+[`data/README.md`](data/README.md) for provenance and how the data was derived.
+
+## Documentation
+
+- [`SCHEMA.md`](SCHEMA.md) — the input data structure (what your export must contain).
+- [`CODING_GUIDE.md`](CODING_GUIDE.md) — how to set up a coding window to produce it.
+- [`data/`](data/) — the derived World Cup sequences, in the canonical format.
+- [`examples/`](examples/) — a runnable quickstart and the reproduction script.
+
+## Tests
+
+```bash
+pip install -e .[test]
+pytest -q
+```
+
+Both the synthetic ground-truth tests and the THEME reproduction tests run
+everywhere — the latter check the detector still reproduces THEME's published
+occurrence counts to the exact N.
+
+## Citation
+
+If you use `tpattern` in research, please cite the software (a machine-readable
+version is in [`CITATION.cff`](CITATION.cff)):
+
+Callaway, A. (2026). *tpattern: open, auditable temporal & sequential analysis for
+sport and behaviour* [Computer software]. Zenodo.
+https://doi.org/10.5281/zenodo.21397543
+
+This DOI is permanent and always resolves to the current release. To pin a specific
+version instead, use that release's own DOI, listed on the Zenodo record.
+
+And the method:
+
+Magnusson, M. S. (2000). Discovering hidden time patterns in behavior: T-patterns
+and their detection. *Behavior Research Methods, Instruments, & Computers*, 32(1),
+93–110. https://doi.org/10.3758/BF03200792
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

tpattern-0.1.0/README.md

@@ -0,0 +1,175 @@
+# tpattern — open, auditable analysis of recurring patterns in event sequences
+
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ajcallaway/TPattern/blob/main/colab/tpattern_guided_analysis.ipynb)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21397543.svg)](https://doi.org/10.5281/zenodo.21397543)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+`tpattern` detects recurring temporal patterns (T-patterns; Magnusson, 2000) in
+**any sequence of timed, labelled events** — behaviour, sport, clinical or
+physiological logs, interaction data — validates them properly against chance, and
+produces clean, publication-ready output (tables, figures, pattern dendrograms). It
+is a free, transparent, reproducible alternative to the THEME software, and the
+analysis companion to the [OpenTag.Studio](https://opentag.studio) tagging tool.
+
+## Two ways to use it
+
+- 🚀 **Google Colab — no coding.** [**Open the guided notebook in Colab**](https://colab.research.google.com/github/ajcallaway/TPattern/blob/main/colab/tpattern_guided_analysis.ipynb): upload your events, follow the guided steps, download a report with a plain-English verdict for every pattern and a paste-ready Methods paragraph. See [`colab/`](colab/).
+- 🐍 **Python library.** `pip install` and script it — see [Quickstart](#quickstart) and [`examples/`](examples/).
+
+Bring your own data (one row per event — see [`SCHEMA.md`](SCHEMA.md)) or try the
+included [`data/`](data/) example.
+
+## Why it exists
+
+T-pattern analysis finds behaviourally meaningful structure that event counts and 
+simple transition tables miss. It is most established through Magnusson's THEME
+software, the reference implementation. `tpattern` is an open, complementary
+implementation that reproduces THEME's detection and adds a reproducible chance
+model and clear reporting:
+
+- **reproduces** THEME's core detection (critical intervals, Nx/T baseline,
+  completeness competition) — validated to the pattern for published datasets;
+- **adds a chance model** — every pattern is tested against a surrogate null, with
+  p-values **corrected for repeated testing** (false-discovery rate and
+  family-wise);
+- **handles concurrency explicitly** — events sharing a timestamp are treated as
+  co-occurrence rather than sequence;
+- **reports clearly** — tidy tables, effect sizes with confidence intervals,
+  purposeful figures, and clean **dendrograms** of the detected patterns.
+
+## Installation
+
+From source (until published on PyPI):
+
+```bash
+git clone https://github.com/ajcallaway/TPattern.git
+cd tpattern
+pip install -e .
+```
+
+Requires Python ≥ 3.9 (depends on numpy, scipy, matplotlib).
+
+## Quickstart
+
+```python
+from tpattern import read_table, Config, recommend, calibrate, report, methods_text
+
+# 1. Load your events — one row per event (observation, event, start).
+#    Pass time_unit="ms" if your times are in milliseconds (default is seconds).
+#    See SCHEMA.md for the (simple) required format.
+observations = read_table("events.csv", time_unit="s")
+
+# 2. Let the tool inspect the data and recommend the method — which surrogate
+#    null, whether to require a genuine lag, which error control — with reasons.
+print(recommend(observations))
+
+# 3. Detect and calibrate in one call: every pattern is tested against a
+#    surrogate null with correction for repeated testing.
+#    (calibrate() runs the detection for you — you don't call detect() first.)
+result = calibrate(observations, Config(), null="profile", B=200, q_target=0.05)
+survivors = result.kept("fdr")     # patterns that survive false-discovery control
+
+# 4. Report: a tidy table (with q-values), pattern dendrograms and a summary —
+#    plus a paste-ready Methods paragraph stating every setting and what it does.
+report(result, "report_out", title="My analysis")
+print(methods_text(Config(), observations=observations, calibration=result))
+```
+
+Two runnable examples:
+
+```bash
+pip install -e .
+python examples/quickstart.py          # no data needed (synthetic ground-truth demo)
+python examples/reproduce_worldcup.py  # a real read_table + full analysis on shipped data
+```
+
+Just want the detected patterns without calibration? `Engine(observations,
+Config()).detect()` returns them directly.
+
+**Comparing two groups** (winner vs loser, goal vs non-goal, condition A vs B)?
+`group_contrast(observations, group_of)` tests each pattern's occurrence between
+the groups (Fisher's exact test, odds ratio + 95% CI) and feeds `forest_plot`.
+
+## The workflow
+
+```
+   tag events            export             analyse                    report
+ (OpenTag / Sportscode) ──────▶ standard ──▶ tpattern ──▶ tables · figures · dendrograms
+                                 table         (detect · validate ·
+                                               calibrate)
+```
+
+1. **Tag** your video/events in any coding tool.
+2. **Export** to the standard input structure — one row per event
+   (`observation, event, start`, plus optional `end`, descriptor and group
+   columns). See [`SCHEMA.md`](SCHEMA.md).
+3. **Set up your coding** so the export is analysis-ready — one event per action,
+   explicit outcomes, unit boundaries. See [`CODING_GUIDE.md`](CODING_GUIDE.md).
+4. **Detect** T-patterns, **validate** them against a surrogate null with corrected
+   significance (`recommend` advises the settings; `calibrate` runs it), and
+   **report** (tables, dendrograms, and a `methods_text` Methods paragraph).
+
+## Relationship to OpenTag.Studio
+
+[OpenTag.Studio](https://opentag.studio) is a free, browser-based sports video
+tagging tool. It is the natural front end for `tpattern`: tag your footage, export
+a session, and analyse it here — no proprietary software anywhere in the pipeline.
+OpenTag's **THEME & GSEQ setup guide** covers how to design a coding window so the
+export is analysis-ready, and that guidance applies directly to `tpattern`
+(`CODING_GUIDE.md` is the short bridge). Together they form a complete, open
+tag → analysis pipeline.
+
+## Reproducing the published results
+
+The derived 2022 World Cup event sequences ship in [`data/`](data/), so the
+published analyses reproduce from this repository alone:
+
+```bash
+python examples/reproduce_worldcup.py              # concordance, exclusion, concurrency (~5 s)
+python examples/reproduce_worldcup.py --calibrate  # also the surrogate null (~10 min)
+```
+
+This regenerates the tpattern-vs-THEME pattern counts by level, the interception
+exclusion divergence, the co-occurrence-vs-sequence analysis, and how many patterns
+survive the surrogate null. All seeded and deterministic. See
+[`data/README.md`](data/README.md) for provenance and how the data was derived.
+
+## Documentation
+
+- [`SCHEMA.md`](SCHEMA.md) — the input data structure (what your export must contain).
+- [`CODING_GUIDE.md`](CODING_GUIDE.md) — how to set up a coding window to produce it.
+- [`data/`](data/) — the derived World Cup sequences, in the canonical format.
+- [`examples/`](examples/) — a runnable quickstart and the reproduction script.
+
+## Tests
+
+```bash
+pip install -e .[test]
+pytest -q
+```
+
+Both the synthetic ground-truth tests and the THEME reproduction tests run
+everywhere — the latter check the detector still reproduces THEME's published
+occurrence counts to the exact N.
+
+## Citation
+
+If you use `tpattern` in research, please cite the software (a machine-readable
+version is in [`CITATION.cff`](CITATION.cff)):
+
+Callaway, A. (2026). *tpattern: open, auditable temporal & sequential analysis for
+sport and behaviour* [Computer software]. Zenodo.
+https://doi.org/10.5281/zenodo.21397543
+
+This DOI is permanent and always resolves to the current release. To pin a specific
+version instead, use that release's own DOI, listed on the Zenodo record.
+
+And the method:
+
+Magnusson, M. S. (2000). Discovering hidden time patterns in behavior: T-patterns
+and their detection. *Behavior Research Methods, Instruments, & Computers*, 32(1),
+93–110. https://doi.org/10.3758/BF03200792
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

tpattern-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tpattern"
+version = "0.1.0"
+description = "Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Andrew Callaway", email = "acallaway@bournemouth.ac.uk" },
+]
+keywords = ["t-pattern", "THEME", "temporal", "sequence", "sport", "behaviour", "notation analysis"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "numpy>=1.21",
+    "scipy>=1.7",
+    "matplotlib>=3.4",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+gui = ["ipywidgets>=8", "pandas>=1.3", "openpyxl>=3"]
+
+[project.urls]
+Homepage = "https://github.com/ajcallaway/TPattern"
+Repository = "https://github.com/ajcallaway/TPattern"
+"Archive (DOI)" = "https://doi.org/10.5281/zenodo.21397543"
+"Tagging tool (OpenTag)" = "https://opentag.studio"
+
+[tool.setuptools]
+packages = ["tpattern"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tpattern-0.1.0/setup.cfg

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

tpattern-0.1.0/tests/test_calibrated_pins.py

@@ -0,0 +1,34 @@
+"""Regression guards for the calibrated pipeline (panel Review-Extras §C):
+the headline q-value the validation paper turns on, detection determinism, and
+the occurrence-equivalence invariant. Nothing else pins these."""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from tpattern import read_table, Config, Engine, calibrate       # noqa: E402
+from tpattern.synthetic import SyntheticSpec, make_dataset        # noqa: E402
+
+DATA = Path(__file__).resolve().parents[1] / "data"
+
+def test_headline_calibrated_number_is_pinned():
+    obs = read_table(DATA / "worldcup_goals.csv", obs_start="obs_start",
+                     obs_end="obs_end", time_unit="ms")
+    r = calibrate(obs, Config(min_lag=1), null="profile", B=2000, seed=20260714)
+    kept = r.kept("fdr")
+    assert len(kept) == 1
+    c = kept[0]
+    assert c.pattern.signature() == "(Cross_Incomplete_NoPressure Shot_Goal_Pressure)"
+    assert c.N == 14
+    assert abs(c.fdr_q - 0.006) < 1e-3          # MC p is deterministic at fixed seed
+
+def test_detection_is_deterministic():
+    obs, _ = make_dataset(SyntheticSpec(seed=7))
+    a = {p.signature(): p.N for p in Engine(obs, Config()).detect()}
+    b = {p.signature(): p.N for p in Engine(obs, Config()).detect()}
+    assert a == b
+
+def test_no_occurrence_duplicates_after_collapse():
+    obs = read_table(DATA / "worldcup_nongoals.csv", obs_start="obs_start",
+                     obs_end="obs_end", time_unit="ms")
+    pats = [p for p in Engine(obs, Config()).detect() if p.level >= 1]
+    keys = [frozenset((i.obs, tuple(sorted(i.tokens))) for i in p.instances) for p in pats]
+    assert len(keys) == len(set(keys))          # one representative per occurrence set

tpattern-0.1.0/tests/test_contrast.py

@@ -0,0 +1,40 @@
+"""group_contrast must recover a pattern planted more heavily in one group, with
+an odds ratio > 1 and a small p-value (ground truth)."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from tpattern import group_contrast                    # noqa: E402
+from tpattern.synthetic import SyntheticSpec, make_dataset  # noqa: E402
+
+
+def _labelled_sample():
+    hi, _ = make_dataset(SyntheticSpec(n_seq=120, planted=[("A", 0), ("B", 1500)],
+                                       plant_fraction=0.40, seed=1))
+    lo, _ = make_dataset(SyntheticSpec(n_seq=120, planted=[("A", 0), ("B", 1500)],
+                                       plant_fraction=0.05, seed=2))
+    for o in hi:
+        o.name = "hi_" + o.name
+    for o in lo:
+        o.name = "lo_" + o.name
+    return hi + lo
+
+
+def test_group_contrast_recovers_planted_difference():
+    obs = _labelled_sample()
+    rows = group_contrast(obs, group_of=lambda o: "high" if o.name.startswith("hi")
+                          else "low")
+    planted = next(r for r in rows if r["signature"] == "(A B)")
+    assert planted["odds_ratio"] > 2.0
+    assert planted["p"] < 0.01
+    assert planted["more_common_in"] == "high"
+
+
+def test_group_contrast_requires_two_groups():
+    obs = _labelled_sample()
+    try:
+        group_contrast(obs, group_of=lambda o: "only_one")
+        assert False, "should reject a single group"
+    except ValueError:
+        pass

tpattern-0.1.0/tests/test_dedup.py

@@ -0,0 +1,33 @@
+"""Occurrence-identical patterns (co-timed reversals, equivalent bracketings) must
+collapse to one representative when collapse_equivalent is on, so the pattern count
+and the multiple-comparison family reflect distinct hypotheses (panel Essential 1)."""
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from tpattern import read_table, Config, Engine  # noqa: E402
+
+DATA = Path(__file__).resolve().parents[1] / "data"
+
+def _occ_keys(pats):
+    return [frozenset((i.obs, tuple(sorted(i.tokens))) for i in p.instances)
+            for p in pats if p.level >= 1]
+
+def test_collapse_removes_occurrence_identical_duplicates():
+    obs = read_table(DATA / "worldcup_nongoals.csv", obs_start="obs_start",
+                     obs_end="obs_end", time_unit="ms")
+    on = [p for p in Engine(obs, Config(min_lag=0, collapse_equivalent=True)).detect()
+          if p.level >= 1]
+    off = [p for p in Engine(obs, Config(min_lag=0, collapse_equivalent=False)).detect()
+           if p.level >= 1]
+    keys_on = _occ_keys(on)
+    # with collapse on, every composite has a distinct occurrence set
+    assert len(keys_on) == len(set(keys_on)), "duplicates survived collapse"
+    # collapse actually removed duplicates that existed without it
+    assert len(on) < len(off), "expected duplicates to be present without collapse"
+
+def test_collapse_does_not_touch_headline():
+    obs = read_table(DATA / "worldcup_goals.csv", obs_start="obs_start",
+                     obs_end="obs_end", time_unit="ms")
+    pats = [p for p in Engine(obs, Config(min_lag=1)).detect() if p.level >= 1]
+    keys = _occ_keys(pats)
+    assert len(keys) == len(set(keys))  # headline path has no duplicates anyway

tpattern-0.1.0/tests/test_guided.py

@@ -0,0 +1,28 @@
+"""The guided wizard's engine (run_analysis) must complete end-to-end and write
+the expected outputs. The widget layer (launch) is UI-only and not tested here."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from tpattern import run_analysis  # noqa: E402
+
+DATA = Path(__file__).resolve().parents[1] / "data" / "worldcup_goals.csv"
+
+pytestmark = pytest.mark.skipif(not DATA.exists(), reason="shipped data not present")
+
+
+def test_run_analysis_end_to_end(tmp_path):
+    res = run_analysis(str(DATA), obs_start="obs_start", obs_end="obs_end",
+                       time_unit="ms", null="profile", min_lag=1, B=50,
+                       outdir=str(tmp_path / "out"), title="test")
+    # it read the 163 goal sequences and captured a recommendation
+    assert "163 observations" in res.recommendation
+    assert res.n_detected > 0
+    # it produced a table, a summary and a Methods statement
+    assert Path(res.files["table"]).exists()
+    assert Path(res.files["summary"]).exists()
+    assert "T-pattern detection was performed with tpattern" in res.methods
+    assert "min_lag = 1" in res.methods  # the chosen setting is documented

tpattern-0.1.0/tests/test_reproduction.py

@@ -0,0 +1,61 @@
+"""
+Reproduction test — the anchor for the paper's reproducibility claim.
+
+The detector must reproduce THEME's published occurrence counts for the World Cup
+Goals sample to the exact N. These anchors were read from the audited manuscript.
+The derived data ships in data/, so this runs everywhere (including CI) rather
+than being skipped.
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from tpattern import read_table, Engine, Config  # noqa: E402
+
+DATA = Path(__file__).resolve().parents[1] / "data" / "worldcup_goals.csv"
+
+# (A, B, expected N) — from the audited World Cup manuscript (Goals sample).
+ANCHORS = [
+    ("Challenge_Pressure", "Shot_Goal_Pressure", 21),
+    ("Challenge_Pressure", "Pass_Complete_Pressure", 21),
+    ("Cross_Incomplete_NoPressure", "Shot_Goal_Pressure", 14),
+    ("Cross_Incomplete_NoPressure", "Shot_Goal_NoPressure", 8),
+    ("Shot_Goal_Pressure", "Challenge_Pressure", 16),
+    ("Shot_Goal_NoPressure", "Challenge_Pressure", 7),
+]
+
+
+@pytest.fixture(scope="module")
+def goals_patterns():
+    obs = read_table(DATA, obs_start="obs_start", obs_end="obs_end", time_unit="ms")
+    assert len(obs) == 163, "expected the 163 goal sequences"
+    return {p.signature(): p for p in Engine(obs, Config()).detect()}
+
+
+@pytest.mark.parametrize("a,b,expected", ANCHORS)
+def test_level1_anchor_counts(goals_patterns, a, b, expected):
+    sig = f"({a} {b})"
+    assert sig in goals_patterns, f"pattern {a} -> {b} not detected"
+    assert goals_patterns[sig].N == expected
+
+
+def test_univariate_count_matches_theme(goals_patterns):
+    # THEME reported 19 univariate (Level 0) event types for Goals.
+    l0 = [p for p in goals_patterns.values() if p.level == 0]
+    assert len(l0) == 19
+
+
+def test_key_trivariate_present(goals_patterns):
+    sig = "(Cross_Incomplete_NoPressure (Challenge_Pressure Shot_Goal_Pressure))"
+    assert sig in goals_patterns
+    assert goals_patterns[sig].N == 6
+
+
+def test_observation_window_is_preserved():
+    """The NX/T baseline depends on the observation window, so the shipped data
+    must carry it explicitly rather than have it inferred from the events."""
+    obs = read_table(DATA, obs_start="obs_start", obs_end="obs_end", time_unit="ms")
+    assert sum(max(o.T, 1) for o in obs) == 1064634