tpattern — open, auditable analysis of recurring patterns in event sequences
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 tagging tool.
Two ways to use it
- 🚀 Google Colab — no coding. Open the guided notebook in Colab: 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/. - 🐍 Python library.
pip installand script it — see Quickstart andexamples/.
Bring your own data (one row per event — see SCHEMA.md) or try the
included 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
pip install tpattern
Add the guided-wizard extras with pip install tpattern[gui]. To work from source
instead (for development or to run the reproduction scripts and shipped data):
git clone https://github.com/ajcallaway/TPattern.git
cd tpattern
pip install -e .
Requires Python ≥ 3.9 (depends on numpy, scipy, matplotlib).
Quickstart
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:
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)
- Tag your video/events in any coding tool.
- Export to the standard input structure — one row per event
(
observation, event, start, plus optionalend, descriptor and group columns). SeeSCHEMA.md. - Set up your coding so the export is analysis-ready — one event per action,
explicit outcomes, unit boundaries. See
CODING_GUIDE.md. - Detect T-patterns, validate them against a surrogate null with corrected
significance (
recommendadvises the settings;calibrateruns it), and report (tables, dendrograms, and amethods_textMethods paragraph).
Relationship to OpenTag.Studio
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/, so the
published analyses reproduce from this repository alone:
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 for provenance and how the data was derived.
Documentation
SCHEMA.md— the input data structure (what your export must contain).CODING_GUIDE.md— how to set up a coding window to produce it.data/— the derived World Cup sequences, in the canonical format.examples/— a runnable quickstart and the reproduction script.
Tests
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):
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.
Metadata
Release files for tpattern 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tpattern-0.1.2.tar.gz | 57.1 kB | Without provenance | Details for tpattern-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tpattern-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for tpattern-0.1.2-py3-none-any.whl |
Total release size: 114.8 kB
Release files / tpattern-0.1.2.tar.gz
| Download URL | tpattern-0.1.2.tar.gz |
|---|---|
| Size | 57.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fda4d7dd9c12029e6e69ac0b5bad47845b33d5aca86fb6bf17d7035a923c8d24
|
|
BLAKE2b-256 checksum How to use checksums |
d318f35e3d6b58016bf1b5875a5e9b67efaa43fca821c9fba56b43c7357ca5fe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.11
|
Release files / tpattern-0.1.2-py3-none-any.whl
| Download URL | tpattern-0.1.2-py3-none-any.whl |
|---|---|
| Size | 57.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
93f4fed56a7e3516cf2a1d62b5ee918a751d4ff6a34bad247d2e0dc84ac7e815
|
|
BLAKE2b-256 checksum How to use checksums |
0c0e594fc48ca2e081adf306f5eaf985e19283d9c757cc0507d907202d89f93e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.11
|
Security for tpattern 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.