tpattern 0.1.13__tar.gz → 0.1.15__tar.gz

{tpattern-0.1.13/tpattern.egg-info → tpattern-0.1.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.13
+Version: 0.1.15
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
 License-Expression: MIT
@@ -36,20 +36,49 @@ 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)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21397543-1682D4.svg)](https://doi.org/10.5281/zenodo.21397543)
+[![R interface](https://img.shields.io/badge/R-interface-276DC3?logo=r&logoColor=white)](#using-tpattern-from-r)
 [![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.
+implements the published T-pattern detection algorithm (Magnusson, 2000) as free,
+auditable code — the same critical-interval method the THEME software applies (see
+[The method it implements](#the-method-it-implements)) — and is the analysis
+companion to the [OpenTag.Studio](https://opentag.studio) tagging tool.
 
-## Two ways to use it
+## Three 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/).
+### 🚀 In your browser — Google Colab, no install, no coding
+
+Open a guided notebook, upload your events CSV, and it walks you through four steps —
+**upload → inspect → the recommended settings appear → run** — then hands back a full
+report inline and as a downloadable zip: a colour-coded results table with a
+plain-English verdict for every pattern (🟢 robust · 🟡 borderline · ⚪ likely chance),
+the pattern dendrograms, the code to restyle them, and a paste-ready Methods paragraph.
+No data of your own yet? Point it at [`data/worldcup_goals.csv`](data/worldcup_goals.csv)
+(choose **ms** for the time unit).
+
+Three notebooks (all in [`colab/`](colab/)):
+
+- [**Guided analysis**](https://colab.research.google.com/github/ajcallaway/TPattern/blob/main/colab/tpattern_guided_analysis.ipynb) — **recommended.** Installs the latest `tpattern` and opens the guided panel. This is the one the badge above opens.
+- **Guided analysis (offline)** — the package is bundled inside the notebook (a snapshot), so it runs where you can't install from GitHub. Open `colab/tpattern_guided_analysis_offline.ipynb` via **File → Upload notebook**.
+- **Worked example** — the companion to the tutorial paper. Runs the load → inspect → recommend → calibrate → report walk-through on the shipped World Cup goal sequences, cell by cell, so you can follow the whole analysis and then swap in your own data (`colab/tpattern_worked_example.ipynb`).
+
+### 🐍 As a Python library
+
+`pip install tpattern` and script it — see [Getting started](#getting-started-in-a-minute), [Quickstart](#quickstart) and [`examples/`](examples/).
+
+### 📊 From R
+
+R users (common in psychology and behavioural science) can drive the **same
+engine** via [`reticulate`](https://rstudio.github.io/reticulate/) — the algorithm
+stays in Python, so results match exactly. Install with
+`remotes::install_github("ajcallaway/TPattern", subdir = "r")`, then run the whole
+analysis in one call: `tpattern_analysis("events.csv")`. See
+[Using tpattern from R](#using-tpattern-from-r).
 
 Bring your own data (one row per event — see [`SCHEMA.md`](SCHEMA.md)) or try the
 included [`data/`](data/) example.
@@ -108,24 +137,47 @@ print(explain("fdr_q"))      # what an output column means
 - **Clean figures** — dendrograms, temporal signatures, forest plots — that share one
   customisable style (`tpattern.viz.STYLE`).
 
-## 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
+## The method it implements
+
+T-pattern analysis (Magnusson, 1996, 2000, 2019) finds behaviourally meaningful
+structure that event counts and simple transition tables miss: event types that
+recur in the same order, separated by statistically consistent time intervals, more
+often than chance predicts. `tpattern` implements the algorithm exactly as published,
+in auditable code:
+
+- **Critical-interval detection.** For an ordered pair of event types (A, B) it
+  searches for the time window after A within which B follows more often than B's
+  overall rate would predict. Significance is the **upper-tail binomial** probability
+  of the observed number of A→B matches, evaluated against that baseline rate (B's
+  occurrences spread over the observation length — the *NX/T* baseline), thresholded
+  at α (default 0.005). This is the critical-interval test set out in Magnusson (2000)
+  and the THEME manual.
+- **Free search, one-to-one matching, distinct tokens.** A free search selects the
+  largest significant interval; occurrences are matched one-to-one by the greedy
+  procedure the algorithm specifies; a pattern must be built from distinct event
+  tokens.
+- **Bottom-up hierarchy with completeness competition.** Patterns are grown level by
+  level, longer patterns competing with their sub-patterns so that only the most
+  complete survive.
+
+On top of the published detection, `tpattern` adds what the method has historically
+lacked:
+
+- **a proper chance model** — every detected pattern is tested against a surrogate
+  null, with p-values **corrected for repeated testing** (Benjamini–Hochberg FDR for
+  screening, Holm family-wise for confirmatory claims), stratified by level;
+- **explicit concurrency handling** — events sharing a timestamp are reported as
   co-occurrence rather than sequence;
-- **reports clearly** — tidy tables, effect sizes with confidence intervals,
+- **clear reporting** — tidy tables, effect sizes with confidence intervals,
   purposeful figures, and clean **dendrograms** of the detected patterns.
 
+The reference software for this method is THEME (PatternVision Ltd), with **SOF-CODER**
+(Jonsson et al., 2006) as its coding front end. `tpattern` reads that ecosystem
+directly — `read_sofcoder` ingests SOF-CODER/THEME (`DATANAME, T, Events`) files — so
+existing THEME datasets can be re-analysed with the surrogate calibration, and
+[OpenTag.Studio](https://opentag.studio) can play, for `tpattern`, the role SOF-CODER
+plays for THEME.
+
 ## Installation
 
 ```bash
@@ -191,6 +243,32 @@ Config()).detect()` returns them directly.
 the groups (Fisher's exact test, odds ratio + 95% CI) and feeds `forest_plot` — or run
 `new_analysis(template="two_groups")` for a ready-made script.
 
+## Using tpattern from R
+
+R users (common in psychology and behavioural science) can drive the **same
+engine** from R — the algorithm stays in Python, called through
+[`reticulate`](https://rstudio.github.io/reticulate/), so results match this
+package and the paper exactly. The R interface lives in [`r/`](r/):
+
+```r
+# install.packages("remotes")
+remotes::install_github("ajcallaway/TPattern", subdir = "r")
+
+library(tpattern)
+install_tpattern()        # once: sets up a Python environment R can use
+
+# the whole analysis in one call — prints what the advisor recommends,
+# calibrates every pattern, writes a report, returns the table:
+out <- tpattern_analysis("my_events.csv", time_unit = "ms")
+out$table
+```
+
+Or step by step: `read_events()` → `advise()` (the advisor, pulled through in
+full) → `calibrate_patterns()` → `results_table()` / `tpattern_report()`, with
+`explain()` for any setting and `new_analysis()` to write a commented starter
+script. See [`r/README.md`](r/README.md). (CRAN release to follow, then
+`install.packages("tpattern")`.)
+
 ## The workflow
 
 ```
@@ -252,9 +330,9 @@ 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.
+Both the synthetic ground-truth tests and the reproduction tests run everywhere —
+the latter check the detector still reproduces the occurrence counts published for
+the reference datasets to the exact N.
 
 ## Citation
 
@@ -268,12 +346,23 @@ 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:
+And the method it implements:
 
 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
 
+The reference software for the method, and its coding front end:
+
+Magnusson, M. S. (2019). T-pattern detection and analysis (TPA) with THEME: A mixed
+methods approach. *Frontiers in Psychology*, 10, 2663.
+https://doi.org/10.3389/fpsyg.2019.02663
+
+Jonsson, G. K., Anguera, M. T., Blanco-Villaseñor, Á., Losada, J. L.,
+Hernández-Mendo, A., Ardá, T., Camerino, O., & Castellano, J. (2006). Hidden
+patterns of play interaction in soccer using SOF-CODER. *Behavior Research Methods*,
+38(3), 372–381. https://doi.org/10.3758/BF03192790
+
 ## License
 
 MIT — see [`LICENSE`](LICENSE).

{tpattern-0.1.13 → tpattern-0.1.15}/README.md

@@ -1,20 +1,49 @@
 # 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)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21397543-1682D4.svg)](https://doi.org/10.5281/zenodo.21397543)
+[![R interface](https://img.shields.io/badge/R-interface-276DC3?logo=r&logoColor=white)](#using-tpattern-from-r)
 [![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.
+implements the published T-pattern detection algorithm (Magnusson, 2000) as free,
+auditable code — the same critical-interval method the THEME software applies (see
+[The method it implements](#the-method-it-implements)) — and is the analysis
+companion to the [OpenTag.Studio](https://opentag.studio) tagging tool.
 
-## Two ways to use it
+## Three 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/).
+### 🚀 In your browser — Google Colab, no install, no coding
+
+Open a guided notebook, upload your events CSV, and it walks you through four steps —
+**upload → inspect → the recommended settings appear → run** — then hands back a full
+report inline and as a downloadable zip: a colour-coded results table with a
+plain-English verdict for every pattern (🟢 robust · 🟡 borderline · ⚪ likely chance),
+the pattern dendrograms, the code to restyle them, and a paste-ready Methods paragraph.
+No data of your own yet? Point it at [`data/worldcup_goals.csv`](data/worldcup_goals.csv)
+(choose **ms** for the time unit).
+
+Three notebooks (all in [`colab/`](colab/)):
+
+- [**Guided analysis**](https://colab.research.google.com/github/ajcallaway/TPattern/blob/main/colab/tpattern_guided_analysis.ipynb) — **recommended.** Installs the latest `tpattern` and opens the guided panel. This is the one the badge above opens.
+- **Guided analysis (offline)** — the package is bundled inside the notebook (a snapshot), so it runs where you can't install from GitHub. Open `colab/tpattern_guided_analysis_offline.ipynb` via **File → Upload notebook**.
+- **Worked example** — the companion to the tutorial paper. Runs the load → inspect → recommend → calibrate → report walk-through on the shipped World Cup goal sequences, cell by cell, so you can follow the whole analysis and then swap in your own data (`colab/tpattern_worked_example.ipynb`).
+
+### 🐍 As a Python library
+
+`pip install tpattern` and script it — see [Getting started](#getting-started-in-a-minute), [Quickstart](#quickstart) and [`examples/`](examples/).
+
+### 📊 From R
+
+R users (common in psychology and behavioural science) can drive the **same
+engine** via [`reticulate`](https://rstudio.github.io/reticulate/) — the algorithm
+stays in Python, so results match exactly. Install with
+`remotes::install_github("ajcallaway/TPattern", subdir = "r")`, then run the whole
+analysis in one call: `tpattern_analysis("events.csv")`. See
+[Using tpattern from R](#using-tpattern-from-r).
 
 Bring your own data (one row per event — see [`SCHEMA.md`](SCHEMA.md)) or try the
 included [`data/`](data/) example.
@@ -73,24 +102,47 @@ print(explain("fdr_q"))      # what an output column means
 - **Clean figures** — dendrograms, temporal signatures, forest plots — that share one
   customisable style (`tpattern.viz.STYLE`).
 
-## 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
+## The method it implements
+
+T-pattern analysis (Magnusson, 1996, 2000, 2019) finds behaviourally meaningful
+structure that event counts and simple transition tables miss: event types that
+recur in the same order, separated by statistically consistent time intervals, more
+often than chance predicts. `tpattern` implements the algorithm exactly as published,
+in auditable code:
+
+- **Critical-interval detection.** For an ordered pair of event types (A, B) it
+  searches for the time window after A within which B follows more often than B's
+  overall rate would predict. Significance is the **upper-tail binomial** probability
+  of the observed number of A→B matches, evaluated against that baseline rate (B's
+  occurrences spread over the observation length — the *NX/T* baseline), thresholded
+  at α (default 0.005). This is the critical-interval test set out in Magnusson (2000)
+  and the THEME manual.
+- **Free search, one-to-one matching, distinct tokens.** A free search selects the
+  largest significant interval; occurrences are matched one-to-one by the greedy
+  procedure the algorithm specifies; a pattern must be built from distinct event
+  tokens.
+- **Bottom-up hierarchy with completeness competition.** Patterns are grown level by
+  level, longer patterns competing with their sub-patterns so that only the most
+  complete survive.
+
+On top of the published detection, `tpattern` adds what the method has historically
+lacked:
+
+- **a proper chance model** — every detected pattern is tested against a surrogate
+  null, with p-values **corrected for repeated testing** (Benjamini–Hochberg FDR for
+  screening, Holm family-wise for confirmatory claims), stratified by level;
+- **explicit concurrency handling** — events sharing a timestamp are reported as
   co-occurrence rather than sequence;
-- **reports clearly** — tidy tables, effect sizes with confidence intervals,
+- **clear reporting** — tidy tables, effect sizes with confidence intervals,
   purposeful figures, and clean **dendrograms** of the detected patterns.
 
+The reference software for this method is THEME (PatternVision Ltd), with **SOF-CODER**
+(Jonsson et al., 2006) as its coding front end. `tpattern` reads that ecosystem
+directly — `read_sofcoder` ingests SOF-CODER/THEME (`DATANAME, T, Events`) files — so
+existing THEME datasets can be re-analysed with the surrogate calibration, and
+[OpenTag.Studio](https://opentag.studio) can play, for `tpattern`, the role SOF-CODER
+plays for THEME.
+
 ## Installation
 
 ```bash
@@ -156,6 +208,32 @@ Config()).detect()` returns them directly.
 the groups (Fisher's exact test, odds ratio + 95% CI) and feeds `forest_plot` — or run
 `new_analysis(template="two_groups")` for a ready-made script.
 
+## Using tpattern from R
+
+R users (common in psychology and behavioural science) can drive the **same
+engine** from R — the algorithm stays in Python, called through
+[`reticulate`](https://rstudio.github.io/reticulate/), so results match this
+package and the paper exactly. The R interface lives in [`r/`](r/):
+
+```r
+# install.packages("remotes")
+remotes::install_github("ajcallaway/TPattern", subdir = "r")
+
+library(tpattern)
+install_tpattern()        # once: sets up a Python environment R can use
+
+# the whole analysis in one call — prints what the advisor recommends,
+# calibrates every pattern, writes a report, returns the table:
+out <- tpattern_analysis("my_events.csv", time_unit = "ms")
+out$table
+```
+
+Or step by step: `read_events()` → `advise()` (the advisor, pulled through in
+full) → `calibrate_patterns()` → `results_table()` / `tpattern_report()`, with
+`explain()` for any setting and `new_analysis()` to write a commented starter
+script. See [`r/README.md`](r/README.md). (CRAN release to follow, then
+`install.packages("tpattern")`.)
+
 ## The workflow
 
 ```
@@ -217,9 +295,9 @@ 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.
+Both the synthetic ground-truth tests and the reproduction tests run everywhere —
+the latter check the detector still reproduces the occurrence counts published for
+the reference datasets to the exact N.
 
 ## Citation
 
@@ -233,12 +311,23 @@ 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:
+And the method it implements:
 
 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
 
+The reference software for the method, and its coding front end:
+
+Magnusson, M. S. (2019). T-pattern detection and analysis (TPA) with THEME: A mixed
+methods approach. *Frontiers in Psychology*, 10, 2663.
+https://doi.org/10.3389/fpsyg.2019.02663
+
+Jonsson, G. K., Anguera, M. T., Blanco-Villaseñor, Á., Losada, J. L.,
+Hernández-Mendo, A., Ardá, T., Camerino, O., & Castellano, J. (2006). Hidden
+patterns of play interaction in soccer using SOF-CODER. *Behavior Research Methods*,
+38(3), 372–381. https://doi.org/10.3758/BF03192790
+
 ## License
 
 MIT — see [`LICENSE`](LICENSE).

{tpattern-0.1.13 → tpattern-0.1.15}/pyproject.toml

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

{tpattern-0.1.13 → tpattern-0.1.15}/tpattern/__init__.py

@@ -6,7 +6,7 @@ behavior: T-patterns and their detection. Behavior Research Methods,
 Instruments, & Computers, 32(1), 93-110.
 """
 
-__version__ = "0.1.13"   # defined before submodule imports (methods.py reads it)
+__version__ = "0.1.15"   # defined before submodule imports (methods.py reads it)
 
 from .io import (Observation, read_observation, read_sample, read_table,
                  read_sofcoder, DataFormatError, check_reference, CHECKS)

{tpattern-0.1.13 → tpattern-0.1.15}/tpattern/significance.py

@@ -66,6 +66,7 @@ class Calibrated:
     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
+    fdr_q_by: float = 1.0     # Benjamini-Yekutieli q (dependence-robust FDR)
 
 
 @dataclass
@@ -81,6 +82,8 @@ class CalibrationResult:
     def kept(self, method: str = "fdr") -> list[Calibrated]:
         if method == "fwer":
             return [c for c in self.real if c.fwer_keep]
+        if method in ("fdr_by", "by"):
+            return [c for c in self.real if c.fdr_q_by <= self.q_target]
         return [c for c in self.real if c.fdr_q <= self.q_target]
 
 
@@ -100,6 +103,20 @@ def _benjamini_hochberg(items, get_p):
     return {id(items[i]): q[i] for i in range(m)}
 
 
+def _benjamini_yekutieli(items, get_p):
+    """Benjamini-Yekutieli q-values: the BH q scaled by the harmonic factor
+    c(m) = sum_{i=1..m} 1/i, which gives false-discovery-rate control under
+    arbitrary dependence among the p-values (Benjamini & Yekutieli, 2001).
+    Surrogate p-values for patterns that share events are dependent, so this is
+    the dependence-robust companion to the BH q; it is more conservative."""
+    m = len(items)
+    if m == 0:
+        return {}
+    cm = sum(1.0 / i for i in range(1, m + 1))
+    bh = _benjamini_hochberg(items, get_p)
+    return {k: min(1.0, v * cm) for k, v in bh.items()}
+
+
 def _holm_keep(items, get_p, alpha):
     """Holm–Bonferroni step-down; return set of ids kept at family alpha."""
     m = len(items)
@@ -217,9 +234,11 @@ def calibrate(observations, config: Config | None = None, *,
         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)
+        bymap = _benjamini_yekutieli(grp, lambda c: c.p_emp)
         for c in grp:
             c.fwer_keep = id(c) in keep
             c.fdr_q = qmap[id(c)]
+            c.fdr_q_by = bymap[id(c)]
 
     return CalibrationResult(real=real, surrogate_counts=surrogate_counts,
                              B=B, alpha=alpha, q_target=q_target, null=null,

{tpattern-0.1.13 → tpattern-0.1.15/tpattern.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.13
+Version: 0.1.15
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
 License-Expression: MIT
@@ -36,20 +36,49 @@ 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)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.21397543-1682D4.svg)](https://doi.org/10.5281/zenodo.21397543)
+[![R interface](https://img.shields.io/badge/R-interface-276DC3?logo=r&logoColor=white)](#using-tpattern-from-r)
 [![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.
+implements the published T-pattern detection algorithm (Magnusson, 2000) as free,
+auditable code — the same critical-interval method the THEME software applies (see
+[The method it implements](#the-method-it-implements)) — and is the analysis
+companion to the [OpenTag.Studio](https://opentag.studio) tagging tool.
 
-## Two ways to use it
+## Three 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/).
+### 🚀 In your browser — Google Colab, no install, no coding
+
+Open a guided notebook, upload your events CSV, and it walks you through four steps —
+**upload → inspect → the recommended settings appear → run** — then hands back a full
+report inline and as a downloadable zip: a colour-coded results table with a
+plain-English verdict for every pattern (🟢 robust · 🟡 borderline · ⚪ likely chance),
+the pattern dendrograms, the code to restyle them, and a paste-ready Methods paragraph.
+No data of your own yet? Point it at [`data/worldcup_goals.csv`](data/worldcup_goals.csv)
+(choose **ms** for the time unit).
+
+Three notebooks (all in [`colab/`](colab/)):
+
+- [**Guided analysis**](https://colab.research.google.com/github/ajcallaway/TPattern/blob/main/colab/tpattern_guided_analysis.ipynb) — **recommended.** Installs the latest `tpattern` and opens the guided panel. This is the one the badge above opens.
+- **Guided analysis (offline)** — the package is bundled inside the notebook (a snapshot), so it runs where you can't install from GitHub. Open `colab/tpattern_guided_analysis_offline.ipynb` via **File → Upload notebook**.
+- **Worked example** — the companion to the tutorial paper. Runs the load → inspect → recommend → calibrate → report walk-through on the shipped World Cup goal sequences, cell by cell, so you can follow the whole analysis and then swap in your own data (`colab/tpattern_worked_example.ipynb`).
+
+### 🐍 As a Python library
+
+`pip install tpattern` and script it — see [Getting started](#getting-started-in-a-minute), [Quickstart](#quickstart) and [`examples/`](examples/).
+
+### 📊 From R
+
+R users (common in psychology and behavioural science) can drive the **same
+engine** via [`reticulate`](https://rstudio.github.io/reticulate/) — the algorithm
+stays in Python, so results match exactly. Install with
+`remotes::install_github("ajcallaway/TPattern", subdir = "r")`, then run the whole
+analysis in one call: `tpattern_analysis("events.csv")`. See
+[Using tpattern from R](#using-tpattern-from-r).
 
 Bring your own data (one row per event — see [`SCHEMA.md`](SCHEMA.md)) or try the
 included [`data/`](data/) example.
@@ -108,24 +137,47 @@ print(explain("fdr_q"))      # what an output column means
 - **Clean figures** — dendrograms, temporal signatures, forest plots — that share one
   customisable style (`tpattern.viz.STYLE`).
 
-## 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
+## The method it implements
+
+T-pattern analysis (Magnusson, 1996, 2000, 2019) finds behaviourally meaningful
+structure that event counts and simple transition tables miss: event types that
+recur in the same order, separated by statistically consistent time intervals, more
+often than chance predicts. `tpattern` implements the algorithm exactly as published,
+in auditable code:
+
+- **Critical-interval detection.** For an ordered pair of event types (A, B) it
+  searches for the time window after A within which B follows more often than B's
+  overall rate would predict. Significance is the **upper-tail binomial** probability
+  of the observed number of A→B matches, evaluated against that baseline rate (B's
+  occurrences spread over the observation length — the *NX/T* baseline), thresholded
+  at α (default 0.005). This is the critical-interval test set out in Magnusson (2000)
+  and the THEME manual.
+- **Free search, one-to-one matching, distinct tokens.** A free search selects the
+  largest significant interval; occurrences are matched one-to-one by the greedy
+  procedure the algorithm specifies; a pattern must be built from distinct event
+  tokens.
+- **Bottom-up hierarchy with completeness competition.** Patterns are grown level by
+  level, longer patterns competing with their sub-patterns so that only the most
+  complete survive.
+
+On top of the published detection, `tpattern` adds what the method has historically
+lacked:
+
+- **a proper chance model** — every detected pattern is tested against a surrogate
+  null, with p-values **corrected for repeated testing** (Benjamini–Hochberg FDR for
+  screening, Holm family-wise for confirmatory claims), stratified by level;
+- **explicit concurrency handling** — events sharing a timestamp are reported as
   co-occurrence rather than sequence;
-- **reports clearly** — tidy tables, effect sizes with confidence intervals,
+- **clear reporting** — tidy tables, effect sizes with confidence intervals,
   purposeful figures, and clean **dendrograms** of the detected patterns.
 
+The reference software for this method is THEME (PatternVision Ltd), with **SOF-CODER**
+(Jonsson et al., 2006) as its coding front end. `tpattern` reads that ecosystem
+directly — `read_sofcoder` ingests SOF-CODER/THEME (`DATANAME, T, Events`) files — so
+existing THEME datasets can be re-analysed with the surrogate calibration, and
+[OpenTag.Studio](https://opentag.studio) can play, for `tpattern`, the role SOF-CODER
+plays for THEME.
+
 ## Installation
 
 ```bash
@@ -191,6 +243,32 @@ Config()).detect()` returns them directly.
 the groups (Fisher's exact test, odds ratio + 95% CI) and feeds `forest_plot` — or run
 `new_analysis(template="two_groups")` for a ready-made script.
 
+## Using tpattern from R
+
+R users (common in psychology and behavioural science) can drive the **same
+engine** from R — the algorithm stays in Python, called through
+[`reticulate`](https://rstudio.github.io/reticulate/), so results match this
+package and the paper exactly. The R interface lives in [`r/`](r/):
+
+```r
+# install.packages("remotes")
+remotes::install_github("ajcallaway/TPattern", subdir = "r")
+
+library(tpattern)
+install_tpattern()        # once: sets up a Python environment R can use
+
+# the whole analysis in one call — prints what the advisor recommends,
+# calibrates every pattern, writes a report, returns the table:
+out <- tpattern_analysis("my_events.csv", time_unit = "ms")
+out$table
+```
+
+Or step by step: `read_events()` → `advise()` (the advisor, pulled through in
+full) → `calibrate_patterns()` → `results_table()` / `tpattern_report()`, with
+`explain()` for any setting and `new_analysis()` to write a commented starter
+script. See [`r/README.md`](r/README.md). (CRAN release to follow, then
+`install.packages("tpattern")`.)
+
 ## The workflow
 
 ```
@@ -252,9 +330,9 @@ 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.
+Both the synthetic ground-truth tests and the reproduction tests run everywhere —
+the latter check the detector still reproduces the occurrence counts published for
+the reference datasets to the exact N.
 
 ## Citation
 
@@ -268,12 +346,23 @@ 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:
+And the method it implements:
 
 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
 
+The reference software for the method, and its coding front end:
+
+Magnusson, M. S. (2019). T-pattern detection and analysis (TPA) with THEME: A mixed
+methods approach. *Frontiers in Psychology*, 10, 2663.
+https://doi.org/10.3389/fpsyg.2019.02663
+
+Jonsson, G. K., Anguera, M. T., Blanco-Villaseñor, Á., Losada, J. L.,
+Hernández-Mendo, A., Ardá, T., Camerino, O., & Castellano, J. (2006). Hidden
+patterns of play interaction in soccer using SOF-CODER. *Behavior Research Methods*,
+38(3), 372–381. https://doi.org/10.3758/BF03192790
+
 ## License
 
 MIT — see [`LICENSE`](LICENSE).