tpattern 0.1.11__tar.gz → 0.1.13__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.11
+Version: 0.1.13
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
 License-Expression: MIT
@@ -54,6 +54,60 @@ analysis companion to the [OpenTag.Studio](https://opentag.studio) tagging tool.
 Bring your own data (one row per event — see [`SCHEMA.md`](SCHEMA.md)) or try the
 included [`data/`](data/) example.
 
+## Getting started in a minute
+
+Install, generate a starter script, point it at your data, run it:
+
+```bash
+pip install tpattern
+python -c "import tpattern; tpattern.new_analysis()"   # writes my_analysis.py
+```
+
+Open `my_analysis.py`, change the two lines marked `# <-- EDIT` (your file and its time
+unit), and run `python my_analysis.py`. It loads your events, **checks the file and tells
+you in plain language about any problem**, recommends the analysis settings with reasons,
+calibrates every pattern against a chance model, and writes a folder of results with a
+plain-English verdict for each pattern.
+
+Doing something more specific? Generate a template for it:
+
+```python
+from tpattern import new_analysis
+new_analysis()                        # one group: detect, calibrate, report
+new_analysis(template="two_groups")   # compare two groups (odds ratios + forest plot)
+new_analysis(template="null_choice")  # core vs shell: which null a pattern survives
+```
+
+Not sure what a setting means? Ask the code — every setting and output column is documented:
+
+```python
+from tpattern import explain
+print(explain("min_lag"))    # what it does, its range, the recommended value, higher vs lower
+print(explain("fdr_q"))      # what an output column means
+```
+
+## What you get
+
+- **Forgiving data import.** `read_table` checks your file as it reads it and reports, in
+  plain language, any problem, how much of the file it affects, and how to fix it — instead
+  of silently dropping rows. Each check has a stable code (Appendix A of the tutorial; also
+  [`PARAMETERS.md`](PARAMETERS.md)).
+- **A proper chance model.** Every 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 hierarchy level.
+- **Temporal reporting.** Beyond *which* patterns are real, the output says *when*: each
+  pattern's occurrence timing (median lag and spread) is reported by default — on the
+  dendrogram, in the table, and in the plain-English verdict — for every pattern.
+- **Readable output.** Results-table columns are named for what they are (`monte_carlo_p`,
+  `fdr_q`, `survives_fwer_holm`, `bout_support`, `duration_median_ms`), and each pattern
+  carries a plain-English `interpretation`. `explain()` documents every setting and column;
+  the full reference is in [`PARAMETERS.md`](PARAMETERS.md).
+- **One reference, everywhere.** Settings and columns live in one registry that generates the
+  code's `explain()`, `PARAMETERS.md`, the Colab form labels, and the tutorial's tables — so
+  the software, the paper and the notebook can't drift apart.
+- **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 
@@ -62,7 +116,7 @@ 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,
+- **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
@@ -109,12 +163,18 @@ print(recommend(observations))
 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")
+# 4. Report: a tidy results table (monte_carlo_p, fdr_q, survives_fwer_holm, the observed
+#    timing, and a plain-English `interpretation` per pattern), pattern dendrograms, the
+#    temporal-signature and occurrence plots, the event-type roles/connections tables, and a
+#    paste-ready Methods paragraph stating every setting and what it does.
+report(result, "report_out", observations=observations, title="My analysis")
 print(methods_text(Config(), observations=observations, calibration=result))
 ```
 
+Prefer not to write the pipeline yourself? `python -c "import tpattern;
+tpattern.new_analysis()"` writes a commented [`my_analysis.py`](examples/my_analysis.py)
+you edit and run (see [Getting started](#getting-started-in-a-minute)).
+
 Two runnable examples:
 
 ```bash
@@ -128,7 +188,8 @@ 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 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.
 
 ## The workflow
 
@@ -179,7 +240,10 @@ survive the surrogate null. All seeded and deterministic. See
 - [`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.
+- [`examples/`](examples/) — a runnable quickstart, the reproduction script, and the
+  `my_analysis.py` / `my_group_comparison.py` / `my_null_choice.py` starter templates.
+- [`PARAMETERS.md`](PARAMETERS.md) — every setting and output column, with range, recommended
+  value, and what higher/lower does (generated from the code, so it never drifts).
 
 ## Tests
 

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

@@ -19,6 +19,60 @@ analysis companion to the [OpenTag.Studio](https://opentag.studio) tagging tool.
 Bring your own data (one row per event — see [`SCHEMA.md`](SCHEMA.md)) or try the
 included [`data/`](data/) example.
 
+## Getting started in a minute
+
+Install, generate a starter script, point it at your data, run it:
+
+```bash
+pip install tpattern
+python -c "import tpattern; tpattern.new_analysis()"   # writes my_analysis.py
+```
+
+Open `my_analysis.py`, change the two lines marked `# <-- EDIT` (your file and its time
+unit), and run `python my_analysis.py`. It loads your events, **checks the file and tells
+you in plain language about any problem**, recommends the analysis settings with reasons,
+calibrates every pattern against a chance model, and writes a folder of results with a
+plain-English verdict for each pattern.
+
+Doing something more specific? Generate a template for it:
+
+```python
+from tpattern import new_analysis
+new_analysis()                        # one group: detect, calibrate, report
+new_analysis(template="two_groups")   # compare two groups (odds ratios + forest plot)
+new_analysis(template="null_choice")  # core vs shell: which null a pattern survives
+```
+
+Not sure what a setting means? Ask the code — every setting and output column is documented:
+
+```python
+from tpattern import explain
+print(explain("min_lag"))    # what it does, its range, the recommended value, higher vs lower
+print(explain("fdr_q"))      # what an output column means
+```
+
+## What you get
+
+- **Forgiving data import.** `read_table` checks your file as it reads it and reports, in
+  plain language, any problem, how much of the file it affects, and how to fix it — instead
+  of silently dropping rows. Each check has a stable code (Appendix A of the tutorial; also
+  [`PARAMETERS.md`](PARAMETERS.md)).
+- **A proper chance model.** Every 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 hierarchy level.
+- **Temporal reporting.** Beyond *which* patterns are real, the output says *when*: each
+  pattern's occurrence timing (median lag and spread) is reported by default — on the
+  dendrogram, in the table, and in the plain-English verdict — for every pattern.
+- **Readable output.** Results-table columns are named for what they are (`monte_carlo_p`,
+  `fdr_q`, `survives_fwer_holm`, `bout_support`, `duration_median_ms`), and each pattern
+  carries a plain-English `interpretation`. `explain()` documents every setting and column;
+  the full reference is in [`PARAMETERS.md`](PARAMETERS.md).
+- **One reference, everywhere.** Settings and columns live in one registry that generates the
+  code's `explain()`, `PARAMETERS.md`, the Colab form labels, and the tutorial's tables — so
+  the software, the paper and the notebook can't drift apart.
+- **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 
@@ -27,7 +81,7 @@ 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,
+- **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
@@ -74,12 +128,18 @@ print(recommend(observations))
 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")
+# 4. Report: a tidy results table (monte_carlo_p, fdr_q, survives_fwer_holm, the observed
+#    timing, and a plain-English `interpretation` per pattern), pattern dendrograms, the
+#    temporal-signature and occurrence plots, the event-type roles/connections tables, and a
+#    paste-ready Methods paragraph stating every setting and what it does.
+report(result, "report_out", observations=observations, title="My analysis")
 print(methods_text(Config(), observations=observations, calibration=result))
 ```
 
+Prefer not to write the pipeline yourself? `python -c "import tpattern;
+tpattern.new_analysis()"` writes a commented [`my_analysis.py`](examples/my_analysis.py)
+you edit and run (see [Getting started](#getting-started-in-a-minute)).
+
 Two runnable examples:
 
 ```bash
@@ -93,7 +153,8 @@ 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 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.
 
 ## The workflow
 
@@ -144,7 +205,10 @@ survive the surrogate null. All seeded and deterministic. See
 - [`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.
+- [`examples/`](examples/) — a runnable quickstart, the reproduction script, and the
+  `my_analysis.py` / `my_group_comparison.py` / `my_null_choice.py` starter templates.
+- [`PARAMETERS.md`](PARAMETERS.md) — every setting and output column, with range, recommended
+  value, and what higher/lower does (generated from the code, so it never drifts).
 
 ## Tests
 

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

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

tpattern-0.1.13/tests/test_reference.py

@@ -0,0 +1,54 @@
+"""The reference registry: coverage, explain(), and the renamed output columns."""
+from tpattern import (SETTINGS, COLUMNS, explain, explain_settings, explain_columns,
+                      parameters_markdown, read_table, Config, calibrate,
+                      patterns_table, Observation)
+
+
+def test_every_setting_is_complete():
+    for s in SETTINGS:
+        for field in ("key", "form", "group", "does", "range", "recommend", "effect"):
+            assert s.get(field), f"{s.get('form')} missing {field}"
+        assert s["group"] in ("A", "B", "C")
+
+
+def test_explain_by_key_and_form_name():
+    a = explain("min_lag")
+    b = explain("minimum_lag_frames")
+    assert a == b and "recommended" in a and "range" in a
+
+
+def test_explain_column_and_unknown():
+    assert "Benjamini" in explain("fdr_q")
+    assert "No setting or column" in explain("does_not_exist")
+
+
+def test_parameters_markdown_covers_all():
+    md = parameters_markdown()
+    for s in SETTINGS:
+        assert s["form"] in md
+    for c in COLUMNS:
+        assert c["key"] in md
+
+
+def _sample():
+    obs = []
+    for i in range(6):
+        ev = [(0, "A"), (300, "B")] + ([(600, "C")] if i < 3 else [])
+        obs.append(Observation(name=f"o{i}", start=0, end=1000, events=ev))
+    return obs
+
+
+def test_output_columns_renamed():
+    res = calibrate(_sample(), Config(min_lag=1), null="profile", B=50, q_target=.05, seed=1)
+    row = patterns_table(res)[0]
+    assert "monte_carlo_p" in row and "survives_fwer_holm" in row
+    assert "p_emp" not in row and "fwer_keep" not in row
+    # every reported column has a registry entry (the tutorial table generates from it)
+    keys = {c["key"] for c in COLUMNS}
+    for col in ("monte_carlo_p", "fdr_q", "survives_fwer_holm", "N", "level", "bout_support"):
+        assert col in keys
+
+
+def test_sort_tolerates_old_name():
+    res = calibrate(_sample(), Config(min_lag=1), null="profile", B=50, q_target=.05, seed=1)
+    patterns_table(res, sort="p_emp")   # must not raise

tpattern-0.1.13/tests/test_starter.py

@@ -0,0 +1,34 @@
+"""The copy-and-adapt analysis template generator and its variants."""
+import ast, pytest
+from tpattern import new_analysis
+from tpattern.starter import TEMPLATES
+
+
+def test_all_templates_are_valid_python():
+    assert set(TEMPLATES) == {"basic", "two_groups", "null_choice"}
+    for name, src in TEMPLATES.items():
+        ast.parse(src)                      # each generated script is valid Python
+        assert "# <-- EDIT" in src and "read_table" in src
+
+
+def test_new_analysis_default_and_named(tmp_path):
+    p = new_analysis(tmp_path / "a.py")
+    assert "recommend" in open(p).read() and "calibrate" in open(p).read()
+    g = new_analysis(tmp_path / "g.py", template="two_groups")
+    assert "group_contrast" in open(g).read() and "forest_plot" in open(g).read()
+    n = new_analysis(tmp_path / "n.py", template="null_choice")
+    assert "compare_nulls" in open(n).read()
+
+
+def test_overwrite_guard_and_bad_name(tmp_path):
+    f = tmp_path / "a.py"
+    new_analysis(f)
+    with pytest.raises(FileExistsError):
+        new_analysis(f)
+    new_analysis(f, overwrite=True)
+    with pytest.raises(ValueError):
+        new_analysis(tmp_path / "x.py", template="nope")
+
+
+def test_basic_template_uses_readable_columns():
+    assert "monte_carlo_p" in TEMPLATES["basic"] and "survives_fwer_holm" in TEMPLATES["basic"]

{tpattern-0.1.11 → tpattern-0.1.13}/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.11"   # defined before submodule imports (methods.py reads it)
+__version__ = "0.1.13"   # defined before submodule imports (methods.py reads it)
 
 from .io import (Observation, read_observation, read_sample, read_table,
                  read_sofcoder, DataFormatError, check_reference, CHECKS)
@@ -24,6 +24,9 @@ from .advisor import recommend
 from .methods import methods_text
 from .guided import run_analysis, launch
 from .contrast import group_contrast, contrast_items
+from .reference import (explain, explain_settings, explain_columns,
+                        parameters_markdown, SETTINGS, COLUMNS)
+from .starter import new_analysis, TEMPLATE
 
 __all__ = [
     "Observation", "read_observation", "read_sample", "read_table", "read_sofcoder",
@@ -40,4 +43,6 @@ __all__ = [
     "recommend", "methods_text",
     "run_analysis", "launch",
     "group_contrast", "contrast_items",
+    "explain", "explain_settings", "explain_columns", "parameters_markdown",
+    "SETTINGS", "COLUMNS", "new_analysis",
 ]

{tpattern-0.1.11 → tpattern-0.1.13}/tpattern/guided.py

@@ -104,8 +104,8 @@ def _write_excel(result, q_target, path):
         rows.append({
             "pattern": str(c.pattern), "N": c.N, "level": c.level,
             "critical_interval": f"[{c.ci[0]},{c.ci[1]}]" if c.ci else "",
-            "p_empirical": round(c.p_emp, 4), "q_FDR": round(c.fdr_q, 4),
-            "survives_FDR": int(c.fdr_q <= q_target), "survives_FWER": int(c.fwer_keep),
+            "monte_carlo_p": round(c.p_emp, 4), "fdr_q": round(c.fdr_q, 4),
+            "survives_fdr": int(c.fdr_q <= q_target), "survives_fwer_holm": int(c.fwer_keep),
         })
     try:
         import pandas as pd

tpattern-0.1.13/tpattern/reference.py

@@ -0,0 +1,214 @@
+"""
+One reference for every setting and every output column.
+=========================================================
+
+The problem this solves: a user meets these names in three places — the Python
+`Config`, the Colab settings form, and the results table — and needs, for each, the
+same four things: what it *is*, what range it takes, what value is *recommended*, and
+what *higher or lower* does to the analysis. Rather than scatter that across
+docstrings, a paper table and the advisor, it lives here once. Everything else is
+generated from it: :func:`explain`, the ``PARAMETERS.md`` reference, the tutorial's
+settings and output-column tables, and the plain-language field labels in the Colab
+form. So the code, the paper and the notebook cannot drift.
+
+Each setting record has:
+  key        the ``Config`` (or read_table/calibrate) argument name
+  form       the friendly name shown in the Colab form and the paper
+  group      A = the data can decide it (the advisor recommends);
+             B = your policy (the data cannot decide it);
+             C = a structural input fixed before analysis
+  does       what it does to the detection, in one line
+  range      the values it accepts
+  recommend  the recommended value, and when
+  effect     what higher / lower (or on / off) means
+"""
+
+from __future__ import annotations
+
+# --- settings ---------------------------------------------------------------
+SETTINGS: list[dict] = [
+    # A. the data can decide these (the advisor recommends them)
+    dict(key="null", form="surrogate_null", group="A",
+         does="Which chance model each detected pattern is tested against.",
+         range="profile, rotation or shuffle.",
+         recommend="profile when event types have their own timing (the advisor decides this from the conditional-uniformity check).",
+         effect="profile tests coupling beyond each type's own timing; rotation and shuffle test whether any temporal structure is present at all."),
+    dict(key="min_lag", form="minimum_lag_frames", group="A",
+         does="The smallest genuine time gap required between two linked events.",
+         range="a whole number of time units, 0 or more.",
+         recommend="1 when many events share a timestamp (the advisor recommends it when more than ~10% of neighbouring events are co-timed); 0 to match THEME.",
+         effect="higher treats more co-timed pairs as co-occurrence, not sequence; 0 lets co-timed events count as ordered (THEME-compatible, but sub-frame order is undefined)."),
+    dict(key="freq_exclude", form="frequent_event_exclusion", group="A",
+         does="Sets aside an over-common event type from building patterns (it is still counted in the baseline).",
+         range="a positive number (mean occurrences per observation, under the default rule); off if empty.",
+         recommend="the advisor flags a type averaging more than ~1.5 occurrences per observation.",
+         effect="lower excludes more (rarer) types; off keeps every type eligible and can flood the results with 'this common event, then anything'."),
+    dict(key="min_occurrence", form="minimum_occurrence", group="A",
+         does="How many times a pattern must recur before it is tested.",
+         range="a whole number, 2 or more (3 is the usual floor).",
+         recommend="3, the floor at which the surrogate test can be calibrated.",
+         effect="higher keeps only more frequent patterns; below 3 the chance test cannot resolve."),
+    dict(key="error_control", form="error_control", group="A",
+         does="Which multiple-testing correction is treated as primary.",
+         range="fdr or fwer.",
+         recommend="fdr to screen many patterns; fwer for a single confirmatory claim.",
+         effect="fdr controls the expected share of false discoveries; fwer controls any false positive at all (stricter, and needs a large B)."),
+    dict(key="B", form="surrogates_B", group="A",
+         does="How many surrogate datasets are drawn for the Monte-Carlo p-value.",
+         range="a whole number, typically hundreds to thousands.",
+         recommend="200 to screen; 2000 or more for a confirmatory or family-wise claim (the smallest possible p is 1/(B+1)).",
+         effect="higher gives a finer p-value and more confidence, at more compute."),
+    # B. your policy (the data cannot decide these)
+    dict(key="alpha", form="detection_alpha", group="B",
+         does="The critical-interval acceptance threshold: a screening gate deciding which candidates are detected, not the basis of inference.",
+         range="between 0 and 1, small (e.g. .005 to .05).",
+         recommend=".005, a convention in sport T-pattern work; the surrogate calibration, not this threshold, is what a claim rests on.",
+         effect="a looser value lets more candidates through to calibration, but does not change which patterns survive it."),
+    dict(key="q_target", form="false_discovery_q", group="B",
+         does="The false-discovery-rate threshold a pattern's q-value must clear.",
+         range="between 0 and 1 (e.g. .05).",
+         recommend=".05.",
+         effect="lower is stricter (fewer patterns reported)."),
+    dict(key="alpha_fwer", form="family_wise_alpha", group="B",
+         does="The family-wise error rate used for confirmatory claims (Holm).",
+         range="between 0 and 1 (e.g. .005).",
+         recommend=".005; a family-wise claim needs B in the thousands to resolve.",
+         effect="lower is stricter; too small a B cannot reach it."),
+    dict(key="min_samples_frac", form="bout_support_percent", group="B",
+         does="The minimum fraction of observations a pattern must appear in to be kept.",
+         range="0 to 100 percent; 0 is off.",
+         recommend="off. Report prevalence rather than filtering on it (Section 4.1 shows why a threshold cuts along the wrong axis).",
+         effect="raising it deletes rare-but-genuine patterns, including well-evidenced ones specific to a subgroup."),
+    dict(key="lumping_factor", form="lumping_factor", group="B",
+         does="If one event nearly always follows another, treat the pair as a single unit so the combinations do not explode.",
+         range="between 0 and 1; off when 0.",
+         recommend="off. The THEME manual illustrates it with 0.9 (a near-deterministic link).",
+         effect="a higher threshold lumps fewer pairs; used mainly to tame very dense data."),
+    dict(key="completeness", form="completeness_competition", group="B",
+         does="Drops a pattern whose every occurrence sits inside a longer detected pattern.",
+         range="on or off.",
+         recommend="on.",
+         effect="off keeps redundant sub-patterns and inflates the counts."),
+    dict(key="collapse_equivalent", form="collapse_equivalent_patterns", group="B",
+         does="Merges patterns with an identical set of occurrences (the two directions of a co-timed pair, or different bracketings of one chain) to one representative.",
+         range="on or off.",
+         recommend="on.",
+         effect="off double-counts perfectly-dependent duplicates and enlarges the multiple-comparison family."),
+    dict(key="include_univariate", form="include_univariate_patterns", group="B",
+         does="Keeps single-event-type entries (Level 0) in the output.",
+         range="on or off.",
+         recommend="on.",
+         effect="off drops the univariate baseline rows."),
+    dict(key="exclude_events", form="force_exclude_events", group="B",
+         does="An explicit list of event types to bar from building patterns, overriding the frequency rule.",
+         range="comma-separated type names, or empty.",
+         recommend="empty, so the frequency rule applies.",
+         effect="listing a type removes it from pattern-building whatever its frequency (used to reproduce a specific analysis)."),
+    # C. structural inputs (fixed before analysis, change every result)
+    dict(key="time_unit", form="time_unit", group="C",
+         does="The unit of the time columns in your file.",
+         range="s or ms.",
+         recommend="whatever your data uses; times are held internally in milliseconds.",
+         effect="sets the unit intervals are reported in; the wrong choice mis-scales every time."),
+    dict(key="obs_window", form="use_observation_window_columns", group="C",
+         does="Reads each observation's window from obs_start / obs_end columns instead of its first and last event.",
+         range="on or off.",
+         recommend="on when your observations have real bounds (a possession, rally or bout usually does).",
+         effect="off takes the window from the events, which shifts every NX/T baseline probability."),
+    dict(key="max_level", form="maximum_depth", group="C",
+         does="A cap on how deep the pattern hierarchy can go.",
+         range="a whole number, 1 or more.",
+         recommend="8; it is rarely reached.",
+         effect="lower yields fewer and simpler patterns and can prevent overload on dense data."),
+    dict(key="collapse_duplicates", form="same_instant_duplicates", group="C",
+         does="Collapses two records of the same event type at an identical timestamp to one point.",
+         range="on or off.",
+         recommend="on for finely-timed data (a double-entry is one point in time); off only on coarsely-timed data where two same-type events might genuinely share a coded time.",
+         effect="off keeps both records, inflating that type's baseline rate."),
+    dict(key="max_edges", form="candidate_edge_cap", group="C",
+         does="A cap on candidate window boundaries per pair (an approximate search for very dense data).",
+         range="a whole number, 0 or more; 0 means exact.",
+         recommend="0 (exact). Set it only on very dense data where the exact search does not finish.",
+         effect="lower is faster but makes the window search approximate rather than exhaustive."),
+]
+
+# --- output columns ---------------------------------------------------------
+COLUMNS: list[dict] = [
+    dict(key="pattern", does="The pattern as text (the signature is its canonical bracketed form)."),
+    dict(key="N", does="Number of occurrences of the pattern across all observations."),
+    dict(key="bouts", does="Number of distinct observations the pattern occurs in."),
+    dict(key="bout_support", does="bouts as a fraction of all observations (the pattern's prevalence)."),
+    dict(key="length", does="Number of event types in the pattern."),
+    dict(key="level", does="Hierarchy depth: 0 is a single event type, 1 a pair, higher levels longer chains."),
+    dict(key="loop", does="1 if the pattern repeats an event type, otherwise 0."),
+    dict(key="critical_interval", does="The accepted time window [d1, d2] within which the later event follows the earlier."),
+    dict(key="duration_median_ms", does="The observed timing of the occurrences: the median gap (with duration_iqr_ms giving the middle half), in milliseconds."),
+    dict(key="monte_carlo_p", does="The Monte-Carlo empirical p-value: the fraction of surrogate datasets in which the pattern is as strong or stronger."),
+    dict(key="fdr_q", does="The Benjamini-Hochberg false-discovery q-value (the screening decision)."),
+    dict(key="survives_fwer_holm", does="The Holm family-wise decision: 1 if the pattern survives family-wise control, 0 if not."),
+]
+
+_GROUP = {"A": "The data can decide it (the advisor recommends)",
+          "B": "Your policy (the data cannot decide it)",
+          "C": "Structural input (fixed before analysis)"}
+
+
+def explain(name: str | None = None) -> str:
+    """Plain-language reference for a setting or output column, or for everything.
+
+    ``explain("min_lag")`` (or its form name ``"minimum_lag_frames"``) describes one
+    setting; ``explain("fdr_q")`` an output column; ``explain()`` prints them all.
+    """
+    if name is None:
+        return explain_settings() + "\n\n" + explain_columns()
+    for s in SETTINGS:
+        if name in (s["key"], s["form"]):
+            return (f"{s['form']} (Config: {s['key']})  [{_GROUP[s['group']]}]\n"
+                    f"  what it does : {s['does']}\n"
+                    f"  range        : {s['range']}\n"
+                    f"  recommended  : {s['recommend']}\n"
+                    f"  higher/lower : {s['effect']}")
+    for c in COLUMNS:
+        if name == c["key"]:
+            return f"{c['key']}  —  {c['does']}"
+    return f"No setting or column named {name!r}. Try explain() to list them all."
+
+
+def explain_settings() -> str:
+    out = ["SETTINGS"]
+    for g in ("A", "B", "C"):
+        out.append(f"\n[{g}] {_GROUP[g]}")
+        for s in SETTINGS:
+            if s["group"] == g:
+                out.append(f"  {s['form']:28s} {s['does']}")
+                out.append(f"  {'':28s} range: {s['range']}  recommended: {s['recommend']}")
+    return "\n".join(out)
+
+
+def explain_columns() -> str:
+    return "OUTPUT COLUMNS\n" + "\n".join(f"  {c['key']:22s} {c['does']}" for c in COLUMNS)
+
+
+def parameters_markdown() -> str:
+    """The full reference as Markdown (used to write PARAMETERS.md)."""
+    L = ["# tpattern parameters and outputs",
+         "",
+         "Every setting and output column, with what it does, its range, the recommended "
+         "value, and what higher or lower means. Generated from `tpattern/reference.py`, "
+         "which is also the source for the tutorial's tables, the Colab form labels and "
+         "`tpattern.explain()`.", ""]
+    for g in ("A", "B", "C"):
+        L += [f"## {_GROUP[g]}", "",
+              "| Setting (form name / `Config`) | What it does | Range | Recommended | Higher / lower |",
+              "|---|---|---|---|---|"]
+        for s in SETTINGS:
+            if s["group"] == g:
+                L.append(f"| **{s['form']}** / `{s['key']}` | {s['does']} | {s['range']} "
+                         f"| {s['recommend']} | {s['effect']} |")
+        L.append("")
+    L += ["## Output columns", "",
+          "| Column | What it is |", "|---|---|"]
+    for c in COLUMNS:
+        L.append(f"| `{c['key']}` | {c['does']} |")
+    L.append("")
+    return "\n".join(L)

{tpattern-0.1.11 → tpattern-0.1.13}/tpattern/report.py

@@ -102,8 +102,8 @@ def patterns_table(source, outfile: str | None = None, ci_unit: str = "ms",
     """Build a results table from a list of `Pattern` or a `CalibrationResult`.
 
     Returns a list of row dicts. If `outfile` is given, also writes CSV.
-    When given a CalibrationResult, includes p_emp, fdr_q, fwer_keep and sorts by
-    p_emp; otherwise sorts by N (descending).
+    When given a CalibrationResult, includes monte_carlo_p, fdr_q, survives_fwer_holm and sorts by
+    monte_carlo_p; otherwise sorts by N (descending).
 
     Every row carries `bouts` (distinct observations the pattern spans) and
     `bout_support` (that as a fraction of the sample). Prevalence is reported rather
@@ -141,19 +141,23 @@ def patterns_table(source, outfile: str | None = None, ci_unit: str = "ms",
             "duration_range_ms": f"[{dur['min']},{dur['max']}]" if dur else None,
         }
         if calibrated:
-            row["p_emp"] = round(it.p_emp, 4)
+            # readable column names (see tpattern/reference.py); the internal
+            # Calibrated attributes (p_emp, fwer_keep) keep their names.
+            row["monte_carlo_p"] = round(it.p_emp, 4)
             row["fdr_q"] = round(it.fdr_q, 4)
-            row["fwer_keep"] = int(it.fwer_keep)
+            row["survives_fwer_holm"] = int(it.fwer_keep)
             row["analytic_strength"] = round(it.strength, 2)  # -log10(analytic p); comparison only
             row["interpretation"] = interpret(p, it.N, it.fdr_q, ci_unit=ci_unit, dur=dur)
         rows.append(row)
 
     key = sort
     if sort == "auto":
-        key = "p_emp" if calibrated else "N"
+        key = "monte_carlo_p" if calibrated else "N"
+    if key in ("p_emp", "fwer_keep"):        # tolerate the old names
+        key = {"p_emp": "monte_carlo_p", "fwer_keep": "survives_fwer_holm"}[key]
     if key == "N":
         rows.sort(key=lambda r: (-r["N"], r["level"]))
-    elif key in ("p_emp", "fdr_q") and calibrated:
+    elif key in ("monte_carlo_p", "fdr_q") and calibrated:
         rows.sort(key=lambda r: (r[key], -r["N"]))
 
     if outfile:
@@ -400,6 +404,6 @@ def report(source, outdir: str, *, ci_unit: str = "ms", title: str = "T-pattern
         for r in rows[:15]:
             line = f"  N={r['N']:>3}  L{r['level']}  {r['pattern']}"
             if calibrated:
-                line += f"   p_emp={r['p_emp']}  q={r['fdr_q']}"
+                line += f"   monte_carlo_p={r['monte_carlo_p']}  q={r['fdr_q']}"
             fh.write(line + "\n")
     return written

tpattern-0.1.13/tpattern/starter.py

@@ -0,0 +1,147 @@
+"""
+Starting points students can copy and adapt.
+=============================================
+
+The tutorial teaches the method on the worked example; this gives a learner a clean
+template for their *own* data. `new_analysis()` writes a heavily commented starter
+script, with every line to change marked and pointers to `explain()` for each setting.
+Three flavours cover the common designs:
+
+    new_analysis()                          # one group: detect, calibrate, report
+    new_analysis(template="two_groups")     # compare two groups (odds ratios + forest plot)
+    new_analysis(template="null_choice")    # core vs shell: which null a pattern survives
+
+It is the "now do it on your own research" bridge.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_BASIC = '''\
+"""
+My T-pattern analysis.  (tpattern.new_analysis — copy and adapt.)
+
+Point this at your own event table and run it. Every line to change is marked # <-- EDIT.
+For any setting, see what it does, its range and the recommended value with:
+    from tpattern import explain;  print(explain("min_lag"))
+Your data: one row per event, with columns  observation, event, start
+(which session/rally/bout the event belongs to, what happened, and when). See SCHEMA.md
+and the tutorial paper for the full walk-through.
+"""
+from tpattern import read_table, recommend, Config, calibrate, report, explain
+
+# 1. LOAD -----------------------------------------------------------------------
+DATA_FILE = "my_events.csv"     # <-- EDIT: your event table (CSV)
+TIME_UNIT = "ms"                # <-- EDIT: "s" or "ms", the unit of your start column
+observations = read_table(DATA_FILE, time_unit=TIME_UNIT, report="all")
+# read_table checks the file as it reads it and prints any problems by code (Appendix A).
+
+# 2. INSPECT + RECOMMEND --------------------------------------------------------
+# The advisor inspects your data and recommends the null, the minimum lag and the error
+# control, each with its reason. Read it, then decide (you are not obliged to follow it).
+print(recommend(observations))
+
+# 3. CONFIGURE ------------------------------------------------------------------
+# Start from the advisor's recommendation. To understand any setting, print its help:
+#   print(explain("min_lag"))   print(explain("surrogate_null"))   print(explain("frequent_event_exclusion"))
+cfg = Config(
+    min_lag=1,          # <-- 1 requires a genuine time gap (recommended for frame-coded data); 0 = THEME-style
+    freq_exclude=1.5,   # <-- set a very common event aside from pattern-building (kept in the counts)
+    # everything else is left at sensible defaults; run explain() to see them
+)
+NULL = "profile"        # <-- "profile" tests coupling beyond each type's own timing (the usual choice)
+B = 2000                # <-- surrogates: 200 to screen many patterns, 2000+ for a confirmatory claim
+
+# 4. CALIBRATE + REPORT ---------------------------------------------------------
+result = calibrate(observations, cfg, null=NULL, B=B, q_target=0.05)
+report(result, "my_output", observations=observations, title="My analysis")
+
+# my_output/ now holds the results table (patterns_table.csv, with monte_carlo_p, fdr_q and
+# survives_fwer_holm), the pattern dendrograms, the temporal-signature plot, the event-type
+# roles and connections tables, and a plain-text SUMMARY. Each pattern's "interpretation"
+# column reads it in plain English. To understand a column:  print(explain("fdr_q"))
+print("\\nDone. Open the my_output/ folder.")
+'''
+
+_TWO_GROUPS = '''\
+"""
+My T-pattern group comparison.  (tpattern.new_analysis(template="two_groups"))
+
+Do patterns occur differently between two groups (winners vs losers, condition A vs B,
+goals vs non-goals)? For each pattern this tests its occurrence between the groups
+(Fisher's exact test, odds ratio with a 95% confidence interval) and draws a forest plot.
+Lines to change are marked # <-- EDIT. Run explain("min_lag") etc. for any setting.
+"""
+import csv
+from tpattern import read_table, Config, group_contrast, forest_plot
+
+# 1. LOAD your events (one row per event: observation, event, start).
+DATA_FILE = "my_events.csv"     # <-- EDIT
+TIME_UNIT = "ms"                # <-- EDIT: "s" or "ms"
+observations = read_table(DATA_FILE, time_unit=TIME_UNIT, report="all")
+
+# 2. GROUP each observation. group_of maps an observation's name to its group label.
+#    Easiest: a two-column CSV (observation,group). <-- EDIT the path and column names.
+group_of = {row["observation"]: row["group"]
+            for row in csv.DictReader(open("my_groups.csv"))}
+
+# 3. CONTRAST: detect patterns and compare their occurrence between the two groups.
+#    min_count drops patterns too rare to compare; raise it to be more conservative.
+items = group_contrast(observations, group_of, Config(min_lag=1), min_count=5)
+
+# 4. PLOT the odds ratios with 95% CIs (a point whose CI excludes 1 differs between groups).
+forest_plot(items, "group_contrast.png", title="Pattern occurrence: group comparison")
+print("wrote group_contrast.png (odds ratios with 95% confidence intervals)")
+'''
+
+_NULL_CHOICE = '''\
+"""
+My null-choice comparison.  (tpattern.new_analysis(template="null_choice"))
+
+Which patterns are genuine coupling, and which are just shared timing? This calibrates
+your data under two nulls and splits the survivors into the CORE (survives both nulls =
+coupling beyond each event's own timing) and the SHELL (survives the rotation null only =
+co-occurrence driven by shared timing). Lines to change are marked # <-- EDIT.
+"""
+from tpattern import read_table, Config, compare_nulls, null_comparison_plot
+
+DATA_FILE = "my_events.csv"     # <-- EDIT
+TIME_UNIT = "ms"                # <-- EDIT: "s" or "ms"
+observations = read_table(DATA_FILE, time_unit=TIME_UNIT, report="all")
+
+# Compare the profile-preserving null (coupling) against the rotation null (any structure).
+# B = 2000 gives a fine Monte-Carlo p; use 200 to explore quickly first.
+cmp = compare_nulls(observations, Config(min_lag=1), nulls=("profile", "rotation"), B=2000)
+print(cmp)   # lists the core and the shell, with each pattern's q under each null
+
+null_comparison_plot(cmp, "null_comparison.png")
+print("\\nwrote null_comparison.png  (core = survives both nulls; shell = rotation only)")
+'''
+
+TEMPLATES = {"basic": _BASIC, "two_groups": _TWO_GROUPS, "null_choice": _NULL_CHOICE}
+_DEFAULT_NAME = {"basic": "my_analysis.py", "two_groups": "my_group_comparison.py",
+                 "null_choice": "my_null_choice.py"}
+
+# kept for backward compatibility (0.1.12 exported TEMPLATE)
+TEMPLATE = _BASIC
+
+
+def new_analysis(path: str | Path | None = None, *, template: str = "basic",
+                 overwrite: bool = False) -> str:
+    """Write a copy-and-adapt analysis template to `path`. Returns the path written.
+
+    `template` is one of ``"basic"`` (one group), ``"two_groups"`` (compare two groups),
+    or ``"null_choice"`` (core vs shell). If `path` is omitted a sensible filename is used.
+
+    >>> from tpattern import new_analysis
+    >>> new_analysis()                          # writes ./my_analysis.py
+    >>> new_analysis(template="two_groups")     # writes ./my_group_comparison.py
+    """
+    if template not in TEMPLATES:
+        raise ValueError(f"template must be one of {sorted(TEMPLATES)}, got {template!r}")
+    p = Path(path) if path is not None else Path(_DEFAULT_NAME[template])
+    if p.exists() and not overwrite:
+        raise FileExistsError(f"{p} already exists; pass overwrite=True to replace it.")
+    p.write_text(TEMPLATES[template])
+    return str(p)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.11
+Version: 0.1.13
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
 License-Expression: MIT
@@ -54,6 +54,60 @@ analysis companion to the [OpenTag.Studio](https://opentag.studio) tagging tool.
 Bring your own data (one row per event — see [`SCHEMA.md`](SCHEMA.md)) or try the
 included [`data/`](data/) example.
 
+## Getting started in a minute
+
+Install, generate a starter script, point it at your data, run it:
+
+```bash
+pip install tpattern
+python -c "import tpattern; tpattern.new_analysis()"   # writes my_analysis.py
+```
+
+Open `my_analysis.py`, change the two lines marked `# <-- EDIT` (your file and its time
+unit), and run `python my_analysis.py`. It loads your events, **checks the file and tells
+you in plain language about any problem**, recommends the analysis settings with reasons,
+calibrates every pattern against a chance model, and writes a folder of results with a
+plain-English verdict for each pattern.
+
+Doing something more specific? Generate a template for it:
+
+```python
+from tpattern import new_analysis
+new_analysis()                        # one group: detect, calibrate, report
+new_analysis(template="two_groups")   # compare two groups (odds ratios + forest plot)
+new_analysis(template="null_choice")  # core vs shell: which null a pattern survives
+```
+
+Not sure what a setting means? Ask the code — every setting and output column is documented:
+
+```python
+from tpattern import explain
+print(explain("min_lag"))    # what it does, its range, the recommended value, higher vs lower
+print(explain("fdr_q"))      # what an output column means
+```
+
+## What you get
+
+- **Forgiving data import.** `read_table` checks your file as it reads it and reports, in
+  plain language, any problem, how much of the file it affects, and how to fix it — instead
+  of silently dropping rows. Each check has a stable code (Appendix A of the tutorial; also
+  [`PARAMETERS.md`](PARAMETERS.md)).
+- **A proper chance model.** Every 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 hierarchy level.
+- **Temporal reporting.** Beyond *which* patterns are real, the output says *when*: each
+  pattern's occurrence timing (median lag and spread) is reported by default — on the
+  dendrogram, in the table, and in the plain-English verdict — for every pattern.
+- **Readable output.** Results-table columns are named for what they are (`monte_carlo_p`,
+  `fdr_q`, `survives_fwer_holm`, `bout_support`, `duration_median_ms`), and each pattern
+  carries a plain-English `interpretation`. `explain()` documents every setting and column;
+  the full reference is in [`PARAMETERS.md`](PARAMETERS.md).
+- **One reference, everywhere.** Settings and columns live in one registry that generates the
+  code's `explain()`, `PARAMETERS.md`, the Colab form labels, and the tutorial's tables — so
+  the software, the paper and the notebook can't drift apart.
+- **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 
@@ -62,7 +116,7 @@ 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,
+- **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
@@ -109,12 +163,18 @@ print(recommend(observations))
 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")
+# 4. Report: a tidy results table (monte_carlo_p, fdr_q, survives_fwer_holm, the observed
+#    timing, and a plain-English `interpretation` per pattern), pattern dendrograms, the
+#    temporal-signature and occurrence plots, the event-type roles/connections tables, and a
+#    paste-ready Methods paragraph stating every setting and what it does.
+report(result, "report_out", observations=observations, title="My analysis")
 print(methods_text(Config(), observations=observations, calibration=result))
 ```
 
+Prefer not to write the pipeline yourself? `python -c "import tpattern;
+tpattern.new_analysis()"` writes a commented [`my_analysis.py`](examples/my_analysis.py)
+you edit and run (see [Getting started](#getting-started-in-a-minute)).
+
 Two runnable examples:
 
 ```bash
@@ -128,7 +188,8 @@ 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 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.
 
 ## The workflow
 
@@ -179,7 +240,10 @@ survive the surrogate null. All seeded and deterministic. See
 - [`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.
+- [`examples/`](examples/) — a runnable quickstart, the reproduction script, and the
+  `my_analysis.py` / `my_group_comparison.py` / `my_null_choice.py` starter templates.
+- [`PARAMETERS.md`](PARAMETERS.md) — every setting and output column, with range, recommended
+  value, and what higher/lower does (generated from the code, so it never drifts).
 
 ## Tests
 

{tpattern-0.1.11 → tpattern-0.1.13}/tpattern.egg-info/SOURCES.txt

@@ -8,9 +8,11 @@ tests/test_guided.py
 tests/test_null_compare.py
 tests/test_outputs.py
 tests/test_read_table_validation.py
+tests/test_reference.py
 tests/test_report_dendrogram.py
 tests/test_reproduction.py
 tests/test_sofcoder.py
+tests/test_starter.py
 tests/test_support_reporting.py
 tests/test_synthetic.py
 tpattern/__init__.py
@@ -24,8 +26,10 @@ tpattern/io.py
 tpattern/methods.py
 tpattern/pattern.py
 tpattern/randomise.py
+tpattern/reference.py
 tpattern/report.py
 tpattern/significance.py
+tpattern/starter.py
 tpattern/synthetic.py
 tpattern/viz.py
 tpattern.egg-info/PKG-INFO