tpattern 0.1.12__tar.gz → 0.1.13__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.12
+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.12 → 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.12 → tpattern-0.1.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tpattern"
-version = "0.1.12"
+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_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.12 → 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.12"   # 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)
@@ -26,6 +26,7 @@ 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",
@@ -43,5 +44,5 @@ __all__ = [
     "run_analysis", "launch",
     "group_contrast", "contrast_items",
     "explain", "explain_settings", "explain_columns", "parameters_markdown",
-    "SETTINGS", "COLUMNS",
+    "SETTINGS", "COLUMNS", "new_analysis",
 ]

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.12 → tpattern-0.1.13/tpattern.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.12
+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.12 → tpattern-0.1.13}/tpattern.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ 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
@@ -28,6 +29,7 @@ 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