tpattern 0.1.0__py3-none-any.whl

tpattern/significance.py

@@ -0,0 +1,218 @@
+"""
+Surrogate-calibrated significance — the mathematically defensible keep/reject.
+=============================================================================
+
+The analytic critical-interval p-value is not trustworthy here (see
+diagnostics.py: the data are strongly non-Poisson, and the detector selects the
+best of many windows and pairs). So we do not threshold it directly. Instead we
+calibrate every detected pattern against surrogate data run through the
+*identical* detection pipeline. Because the surrogate detection performs the same
+window/pair selection, the comparison is automatically corrected for selection
+bias; because the surrogate preserves each event type's real marginal structure
+(profile-preserving null), it is also corrected for the wrong independence
+assumption.
+
+Per Andy's decision we compute TWO statistics side by side:
+
+1. Signature-matched empirical p (primary, interpretable). For each real pattern,
+   how often does the *same* pattern (identical signature) arise in the
+   surrogates with an occurrence count at least as high?
+       p_emp = (1 + #surrogates with that signature at N >= observed) / (1 + B)
+   This asks, directly, "could chance have produced THIS pattern this strongly?"
+   The +1/+1 is the standard Monte-Carlo correction (never reports p = 0).
+
+2. Analytic strength (secondary). s = -log10(best-window binomial p), calibrated
+   the same way against the pooled surrogate strength distribution. Reported for
+   comparison / robustness, not as the primary decision.
+
+Two error-rate controls, both stratified by pattern level (the search space, and
+hence the null, differs by level):
+
+* FWER (family-wise) — a real pattern is kept only if its empirical p survives a
+  Holm–Bonferroni step-down at level alpha across the patterns of its level.
+  Controls P(any false pattern) <= alpha. Conservative; confirmatory.
+* FDR (false discovery rate) — Benjamini–Hochberg on the empirical p-values at
+  q_target. Controls the expected proportion of false patterns; more powerful,
+  for screening.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from collections import defaultdict
+from dataclasses import dataclass
+
+import numpy as np
+
+from .detect import Config, Engine
+from .randomise import build_profiles, profile_surrogate, randomise_sample
+from .pattern import Pattern
+
+
+def _strength(p: Pattern) -> float:
+    pv = p.p_value if p.p_value and p.p_value > 0 else 1e-300
+    return -math.log10(pv)
+
+
+@dataclass
+class Calibrated:
+    pattern: Pattern
+    level: int
+    N: int
+    ci: tuple
+    p_emp: float = 1.0        # signature-matched empirical p (primary)
+    strength: float = 0.0     # analytic -log10(p) (secondary)
+    p_emp_strength: float = 1.0   # empirical p of the analytic strength
+    fwer_keep: bool = False   # Holm on p_emp
+    fdr_q: float = 1.0        # Benjamini-Hochberg q on p_emp
+
+
+@dataclass
+class CalibrationResult:
+    real: list[Calibrated]
+    surrogate_counts: dict     # level -> list of per-surrogate pattern counts
+    B: int
+    alpha: float
+    q_target: float
+    null: str
+
+    def kept(self, method: str = "fdr") -> list[Calibrated]:
+        if method == "fwer":
+            return [c for c in self.real if c.fwer_keep]
+        return [c for c in self.real if c.fdr_q <= self.q_target]
+
+
+def _benjamini_hochberg(items, get_p):
+    """Assign BH q-values (in place ordering) to `items` by their p = get_p(x)."""
+    m = len(items)
+    if m == 0:
+        return {}
+    order = sorted(range(m), key=lambda i: get_p(items[i]))
+    q = [0.0] * m
+    running = 1.0
+    for rank in range(m - 1, -1, -1):
+        i = order[rank]
+        val = get_p(items[i]) * m / (rank + 1)
+        running = min(running, val)
+        q[i] = min(1.0, running)
+    return {id(items[i]): q[i] for i in range(m)}
+
+
+def _holm_keep(items, get_p, alpha):
+    """Holm–Bonferroni step-down; return set of ids kept at family alpha."""
+    m = len(items)
+    order = sorted(range(m), key=lambda i: get_p(items[i]))
+    kept = set()
+    for rank, i in enumerate(order):
+        if get_p(items[i]) <= alpha / (m - rank):
+            kept.add(id(items[i]))
+        else:
+            break
+    return kept
+
+
+def calibrate(observations, config: Config | None = None, *,
+              null: str = "profile", B: int = 200, alpha: float = 0.005,
+              q_target: float = 0.05, seed: int = 20260714) -> CalibrationResult:
+    """Detect T-patterns, then test each one against a surrogate null.
+
+    This is the main analysis call: it runs the detection for you and calibrates
+    every detected pattern, so you do not need to call Engine.detect() first.
+
+    Parameters
+    ----------
+    observations : list[Observation]
+        The sample, e.g. from read_table().
+    config : Config, optional
+        Detection settings (defaults match THEME). Use Config(min_lag=1) to require
+        a genuine temporal lag on frame-coded data. See advisor.recommend() for a
+        data-driven suggestion.
+    null : {"profile", "rotation", "shuffle"}
+        The surrogate null. "profile" preserves each event type's marginal timing and
+        destroys only cross-type coupling (recommended where timing is structured);
+        "rotation"/"shuffle" are THEME-style nulls.
+    B : int
+        Number of surrogate datasets. The empirical p-value cannot fall below
+        1/(B+1), so family-wise (FWER) claims need B in the thousands; FDR is fine
+        at B=200.
+    alpha, q_target : float
+        Family-wise level (Holm) and false-discovery target (Benjamini-Hochberg).
+    seed : int
+        Fixes the surrogate draw, so results are reproducible.
+
+    Returns
+    -------
+    CalibrationResult
+        Call .kept("fdr") or .kept("fwer") for the surviving patterns; each carries
+        an empirical p (.p_emp) and q-value (.fdr_q).
+    """
+    config = config or Config()
+
+    real_pats = [p for p in Engine(observations, config).detect() if p.level >= 1]
+    real = [Calibrated(pattern=p, level=p.level, N=p.N, ci=p.ci,
+                       strength=_strength(p)) for p in real_pats]
+
+    profiles = build_profiles(observations) if null == "profile" else None
+    np_rng = np.random.default_rng(seed)
+
+    # signature-matched: per real signature, how many surrogates reach its N
+    sig_N = {p.signature(): p.N for p in real_pats}
+    beat_count: dict[str, int] = defaultdict(int)          # count-based
+    # analytic-strength: pooled surrogate strengths per level for empirical p
+    surr_strengths: dict[int, list[float]] = defaultdict(list)
+    surrogate_counts: dict[int, list[int]] = defaultdict(list)
+    track_levels = {c.level for c in real}
+
+    # Monte-Carlo core: generate B surrogate datasets and run the *identical*
+    # detector on each. Because detection performs the same window/pair selection
+    # on the surrogates as on the real data, comparing counts is automatically
+    # corrected for the detector's selection bias.
+    for b in range(B):
+        if null == "profile":
+            surr = profile_surrogate(observations, profiles, np_rng)
+        else:
+            surr = randomise_sample(observations, null, random.Random(seed + b))
+        pats = [p for p in Engine(surr, config).detect() if p.level >= 1]
+
+        # For this one surrogate, record the strongest occurrence count reached by
+        # each pattern signature, and collect the analytic strengths for each level.
+        best_by_sig: dict[str, int] = {}
+        per_level_strength: dict[int, list[float]] = defaultdict(list)
+        for p in pats:
+            sig = p.signature()
+            if p.N > best_by_sig.get(sig, 0):
+                best_by_sig[sig] = p.N
+            per_level_strength[p.level].append(_strength(p))
+        # A surrogate "beats" a real pattern when the *same* signature occurs in it
+        # at least as often as in the real data — i.e. chance reproduced it this
+        # strongly. Tally those hits per signature across all B surrogates.
+        for sig, n_obs in sig_N.items():
+            if best_by_sig.get(sig, 0) >= n_obs:
+                beat_count[sig] += 1
+        # Also pool the surrogate strengths per level, and record how many patterns
+        # this surrogate produced at each level (used for the analytic-strength p
+        # and for the reported surrogate-count distribution).
+        for lv in track_levels:
+            surr_strengths[lv].extend(per_level_strength.get(lv, []))
+            surrogate_counts[lv].append(len(per_level_strength.get(lv, [])))
+
+    # empirical p-values (Monte-Carlo, +1/+1 correction)
+    for c in real:
+        sig = c.pattern.signature()
+        c.p_emp = (1 + beat_count.get(sig, 0)) / (1 + B)
+        pool = surr_strengths.get(c.level, [])
+        ge = sum(1 for s in pool if s >= c.strength)
+        c.p_emp_strength = (1 + ge) / (1 + len(pool)) if pool else 1.0 / (1 + B)
+
+    # per-level FWER (Holm) and FDR (BH) on the primary empirical p
+    for lv in track_levels:
+        grp = [c for c in real if c.level == lv]
+        keep = _holm_keep(grp, lambda c: c.p_emp, alpha)
+        qmap = _benjamini_hochberg(grp, lambda c: c.p_emp)
+        for c in grp:
+            c.fwer_keep = id(c) in keep
+            c.fdr_q = qmap[id(c)]
+
+    return CalibrationResult(real=real, surrogate_counts=surrogate_counts,
+                             B=B, alpha=alpha, q_target=q_target, null=null)

tpattern/synthetic.py

@@ -0,0 +1,95 @@
+"""
+Synthetic ground-truth validation.
+==================================
+
+A "nothing survives" result is only meaningful if the method is *able* to find
+real patterns and *refrains* from inventing them. This module builds data where
+the truth is known, so we can measure both:
+
+* Power / sensitivity  — when we plant a genuine A->B(->C) coupling in a fraction
+  of sequences, does the calibrated detector recover it, and at what strength?
+* Calibration / specificity — on pure-null data (no planted coupling), does the
+  family-wise error rate stay at alpha (FWER) and the false-discovery proportion
+  at q (FDR)? If a method flags patterns in pure noise, it is broken.
+
+Construction. Each sequence is a window [0, T]. Every event type has a marginal
+temporal profile (where in the window it tends to fall) and a per-sequence count,
+mirroring the real data's structure. Background events are placed independently
+from their profiles — so there is NO cross-type coupling by construction. A
+planted pattern adds, in a chosen fraction of sequences, events A, B (, C) at a
+fixed inter-event lag plus jitter — a genuine, known temporal coupling. Anything
+the detector reports other than the planted pattern is, by construction, a false
+positive.
+
+This is deliberately generated independently of the tpattern engine so it is a
+true external test, not a tautology.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .io import Observation
+
+
+@dataclass
+class SyntheticSpec:
+    n_seq: int = 300
+    T: int = 6000                       # window length (ms)
+    bg_types: int = 8                   # number of background event types
+    bg_rate: float = 2.0               # mean background events per type per seq
+    # planted pattern: sequence of (label, lag_ms_from_previous)
+    planted: list = field(default_factory=lambda: [("A", 0), ("B", 1500)])
+    plant_fraction: float = 0.15        # fraction of sequences carrying it
+    jitter: int = 200                   # +/- ms jitter on planted lags
+    seed: int = 7
+
+
+def _profile_time(rng, T, kind):
+    """Draw a within-window time for a background event given a profile kind."""
+    if kind == "early":
+        u = rng.beta(2, 5)
+    elif kind == "late":
+        u = rng.beta(5, 2)
+    else:
+        u = rng.random()
+    return int(u * T)
+
+
+def make_dataset(spec: SyntheticSpec):
+    """Return (observations, truth_signature) for one synthetic spec."""
+    rng = np.random.default_rng(spec.seed)
+    kinds = ["early", "mid", "late"]
+    type_kind = {f"bg{i}": kinds[i % 3] for i in range(spec.bg_types)}
+
+    obs = []
+    n_plant = int(round(spec.n_seq * spec.plant_fraction))
+    plant_flags = np.array([i < n_plant for i in range(spec.n_seq)])
+    rng.shuffle(plant_flags)
+
+    for s in range(spec.n_seq):
+        events = []
+        # background: each type gets Poisson(bg_rate) events from its profile
+        for ev, kind in type_kind.items():
+            c = rng.poisson(spec.bg_rate)
+            for _ in range(c):
+                events.append((_profile_time(rng, spec.T, kind), ev))
+        # planted coupling in a fraction of sequences
+        if plant_flags[s]:
+            anchor = int(rng.uniform(0.1, 0.6) * spec.T)
+            t = anchor
+            for lbl, lag in spec.planted:
+                t = t + lag + int(rng.integers(-spec.jitter, spec.jitter + 1))
+                events.append((max(0, min(spec.T, t)), lbl))
+        events.sort()
+        obs.append(Observation(name=f"syn{s}", start=0, end=spec.T, events=events))
+
+    truth = "(" * (len(spec.planted) - 1)
+    # build the expected signature the same way Pattern.signature would (left-assoc)
+    labels = [lbl for lbl, _ in spec.planted]
+    sig = labels[0]
+    for lbl in labels[1:]:
+        sig = f"({sig} {lbl})"
+    return obs, sig

tpattern/viz.py

@@ -0,0 +1,107 @@
+"""
+Visual output for detected T-patterns — clean, publication-ready figures.
+
+The centrepiece is `pattern_dendrogram`: a T-pattern is a binary tree of
+critical-interval links, and this draws it as a proper dendrogram — event types
+as leaves, each internal join annotated with its critical interval [d1, d2] (the
+time window within which the right side follows the left). THEME draws this as a
+cramped detection tree; here it is a clean, labelled figure.
+"""
+
+from __future__ import annotations
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+from .pattern import Pattern
+
+
+def _layout(p: Pattern, leaves: list, pos: dict):
+    """Assign (x, depth) to every node. Leaves get sequential x; internal nodes
+    sit at the mid-x of their children, depth = 1 + max child depth."""
+    if p.is_terminal:
+        x = len(leaves)
+        leaves.append(p.event)
+        pos[id(p)] = (x, 0)
+        return x, 0
+    lx, ld = _layout(p.left, leaves, pos)
+    rx, rd = _layout(p.right, leaves, pos)
+    x = (lx + rx) / 2.0
+    d = 1 + max(ld, rd)
+    pos[id(p)] = (x, d)
+    return x, d
+
+
+def _draw(p: Pattern, pos: dict, ax, ci_unit: str):
+    """Recursively draw dendrogram elbows from each internal node to its children."""
+    if p.is_terminal:
+        return
+    x, d = pos[id(p)]
+    for child in (p.left, p.right):
+        cx, cd = pos[id(child)]
+        # elbow: up from child to this node's depth, then across
+        ax.plot([cx, cx], [cd, d], color="#34495e", lw=1.4)
+        ax.plot([cx, x], [d, d], color="#34495e", lw=1.4)
+        _draw(child, pos, ax, ci_unit)
+    # annotate the critical interval on the join
+    if p.ci is not None:
+        d1, d2 = p.ci
+        ax.annotate(f"[{d1},{d2}]{ci_unit}", (x, d), textcoords="offset points",
+                    xytext=(0, 4), ha="center", fontsize=7, color="#c0392b")
+
+
+def pattern_dendrogram(pattern: Pattern, title: str | None = None,
+                       ci_unit: str = "", outfile: str | None = None, ax=None):
+    """Draw one T-pattern as a dendrogram. Returns the Axes.
+
+    Leaves (event types) are labelled along the bottom in temporal order; each
+    internal join shows its critical interval. `pattern.N` and significance can
+    be put in the title.
+    """
+    leaves: list = []
+    pos: dict = {}
+    _layout(pattern, leaves, pos)
+
+    own = ax is None
+    if own:
+        fig, ax = plt.subplots(figsize=(max(4, 1.1 * len(leaves)), 3.2))
+    _draw(pattern, pos, ax, ci_unit)
+
+    # leaf labels
+    for i, name in enumerate(leaves):
+        ax.plot([i], [0], "o", color="#2980b9", ms=6)
+        ax.annotate(name, (i, 0), textcoords="offset points", xytext=(0, -8),
+                    ha="right", va="top", rotation=35, fontsize=8)
+
+    ax.set_xlim(-0.7, len(leaves) - 0.3)
+    ax.set_ylim(-1.2, pattern.level + 0.6)
+    ax.set_yticks(range(pattern.level + 1))
+    ax.set_ylabel("level")
+    ax.set_xticks([])
+    for s in ("top", "right", "bottom"):
+        ax.spines[s].set_visible(False)
+    if title:
+        ax.set_title(title, fontsize=9, wrap=True)
+
+    if own and outfile:
+        plt.tight_layout(); plt.savefig(outfile, dpi=150); plt.close()
+    return ax
+
+
+def patterns_overview(patterns: list, outfile: str, max_rows: int = 8,
+                      ci_unit: str = "", by=lambda p: -p.N):
+    """A grid of the top pattern dendrograms (by `by`, default most frequent)."""
+    comps = sorted([p for p in patterns if p.level >= 1], key=by)[:max_rows]
+    n = len(comps)
+    if not n:
+        return
+    cols = 2
+    rows = (n + cols - 1) // cols
+    fig, axes = plt.subplots(rows, cols, figsize=(12, 3.0 * rows))
+    axes = axes.flatten() if n > 1 else [axes]
+    for ax, p in zip(axes, comps):
+        pattern_dendrogram(p, title=f"N={p.N}, level {p.level}", ci_unit=ci_unit, ax=ax)
+    for ax in axes[n:]:
+        ax.axis("off")
+    plt.tight_layout(); plt.savefig(outfile, dpi=150); plt.close()

tpattern-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+tpattern/__init__.py,sha256=8S-AKvLjy8XRYkhyTAE5uuNppoR8ETFN42yHy2ayKqI,1408
+tpattern/advisor.py,sha256=72g-0Q1ANwLmV-lN3dsmCHGKVyvs2YXZCDBSsm4ATLw,10138
+tpattern/ci.py,sha256=SZQ-ljLdg5LTTxsuuHbccOPEqI7cze0Ldv9K3IiDvcU,12896
+tpattern/contrast.py,sha256=VHxKoFNJtauouyAsn0awtvtzukrfueFeu3nVbT120dM,3808
+tpattern/detect.py,sha256=0iRyzOOJARXIId23K77R23kJhKxORGG9sRnuXLT4qdU,16449
+tpattern/diagnostics.py,sha256=i2Os9NQIZFngWzZGaoZ972CWDIcyKZjvdUYw4vSW310,5207
+tpattern/guided.py,sha256=pPhaHYwh2Yxf9Z2hl861HRcbboEE3SzEB7vOjMV3SQo,18676
+tpattern/io.py,sha256=7TTxDcXz4Mx9Edp-tOBPyoUXZhF8R1i4z4dhXfFtMAM,8823
+tpattern/methods.py,sha256=HotEOb6KuMaSpeOUkDXHD9p4x0DesA7uK41GUtxodQg,7095
+tpattern/pattern.py,sha256=XM0NR_8rvQ61LqWceHDwlYLKi6h-TTm0oUF92SbNKrg,5122
+tpattern/randomise.py,sha256=32wG2p5YKYc7UREq-NJsoYUqJ_iudmM7T92rhISmdeA,8922
+tpattern/report.py,sha256=sHoYBifYz4Y3r9XE_CG9jorjadpJ1lhxHt9qSbunFxk,8298
+tpattern/significance.py,sha256=kxFya9vLzlUzQ_4p5q-2fXGyQSdMXRX8pYwA6g_F6VM,9332
+tpattern/synthetic.py,sha256=acSi1FKdF5TJPiRJdR4FIGD2H1CHhIL3C3dz537p5AA,3826
+tpattern/viz.py,sha256=rmrzdWWcUhVtbC0kiOqadW1iwXiDPm5ZXLjhn4J6nuI,3899
+tpattern-0.1.0.dist-info/licenses/LICENSE,sha256=mwn2NKwnIh3O8I2cT9Fd9HAw9sGgdMixJ3BSvE4sOlE,1072
+tpattern-0.1.0.dist-info/METADATA,sha256=EqTmPsjaJvtBDTmlzzHcmTLFJnPIAmERB4Ropo3Pgno,9666
+tpattern-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+tpattern-0.1.0.dist-info/top_level.txt,sha256=PTSDtDgp6IheACBj7DpFWRM6BYG2Ms0cxnuBy4yK4aA,9
+tpattern-0.1.0.dist-info/RECORD,,

tpattern-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tpattern-0.1.0.dist-info/licenses/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.