tpattern 0.1.1__tar.gz → 0.1.4__tar.gz

{tpattern-0.1.1/tpattern.egg-info → tpattern-0.1.4}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.1
+Version: 0.1.4
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/ajcallaway/TPattern
 Project-URL: Repository, https://github.com/ajcallaway/TPattern
 Project-URL: Archive (DOI), https://doi.org/10.5281/zenodo.21397543
@@ -15,7 +15,6 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering

{tpattern-0.1.1 → tpattern-0.1.4}/pyproject.toml

@@ -1,14 +1,15 @@
 [build-system]
-requires = ["setuptools>=61"]
+requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "tpattern"
-version = "0.1.1"
+version = "0.1.4"
 description = "Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour"
 readme = "README.md"
 requires-python = ">=3.9"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [
     { name = "Andrew Callaway", email = "acallaway@bournemouth.ac.uk" },
 ]
@@ -20,7 +21,6 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Intended Audience :: Science/Research",
     "Topic :: Scientific/Engineering",

{tpattern-0.1.1 → tpattern-0.1.4}/tests/test_dedup.py

@@ -31,3 +31,17 @@ def test_collapse_does_not_touch_headline():
     pats = [p for p in Engine(obs, Config(min_lag=1)).detect() if p.level >= 1]
     keys = _occ_keys(pats)
     assert len(keys) == len(set(keys))  # headline path has no duplicates anyway
+
+
+def test_same_time_same_type_duplicates_collapse():
+    """Same-type events at an identical timestamp collapse to one point (default);
+    they are retained only when the option is explicitly disabled."""
+    from tpattern import Observation, Engine, Config
+    obs = [Observation(name="o", start=0, end=200,
+                       events=[(0, "A"), (0, "A"), (100, "A"), (0, "B")])]
+    eng = Engine(obs, Config()); eng.build_terminals()
+    n_A = next(p.N for p in eng.univariate if p.event == "A")
+    assert n_A == 2, f"collapse: A should be 2 distinct points, got {n_A}"
+    eng2 = Engine(obs, Config(collapse_duplicates=False)); eng2.build_terminals()
+    n_A2 = next(p.N for p in eng2.univariate if p.event == "A")
+    assert n_A2 == 3, f"no-collapse: A should retain all 3, got {n_A2}"

tpattern-0.1.4/tests/test_support_reporting.py

@@ -0,0 +1,84 @@
+"""Bout support is *reported*, not filtered on.
+
+The support threshold (`min_samples_frac`) is a prevalence filter, not a
+significance test, so the library's job is to make prevalence visible rather than
+to cut on it. These tests pin that contract: every results row carries the number
+of distinct bouts and the support fraction, and the profile plot renders from a
+calibration result.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from tpattern import (Config, Engine, calibrate, patterns_table,  # noqa: E402
+                      support_profile)
+from tpattern.synthetic import SyntheticSpec, make_dataset  # noqa: E402
+
+
+def _sample():
+    spec = SyntheticSpec(n_seq=120, planted=[("A", 0), ("B", 1500)],
+                         plant_fraction=0.35, seed=5)
+    obs, truth = make_dataset(spec)
+    return obs, truth
+
+
+def test_table_reports_bouts_and_support():
+    obs, _ = _sample()
+    result = calibrate(obs, Config(min_lag=1), null="profile", B=30, seed=1)
+    rows = patterns_table(result)
+    assert rows, "expected at least one detected pattern"
+    for row in rows:
+        # bouts counts DISTINCT observations; N counts occurrences and may exceed it
+        assert 1 <= row["bouts"] <= len(obs)
+        assert row["bouts"] <= row["N"]
+        assert 0.0 < row["bout_support"] <= 1.0
+        assert abs(row["bout_support"] - row["bouts"] / len(obs)) < 1e-6
+
+
+def test_support_needs_sample_size_when_uncalibrated():
+    """A plain pattern list has no sample size, so support is None unless given."""
+    obs, _ = _sample()
+    pats = [p for p in Engine(obs, Config(min_lag=1)).detect() if p.level >= 1]
+    assert patterns_table(pats)[0]["bout_support"] is None
+    rows = patterns_table(pats, n_observations=len(obs))
+    assert rows[0]["bout_support"] is not None
+
+
+def test_calibration_result_carries_sample_size():
+    obs, _ = _sample()
+    result = calibrate(obs, Config(min_lag=1), null="profile", B=30, seed=1)
+    assert result.n_observations == len(obs)
+
+
+def test_support_profile_renders(tmp_path):
+    obs, _ = _sample()
+    result = calibrate(obs, Config(min_lag=1), null="profile", B=30, seed=1)
+    out = tmp_path / "profile.png"
+    key = support_profile(result, str(out), mark_thresholds=(0.10,))
+    assert out.exists() and out.stat().st_size > 0
+    # returned key is ordered by descending support, so a caption can be built from it
+    assert key == sorted(key, key=lambda kv: -kv[1])
+
+
+def test_support_profile_handles_no_survivors(tmp_path):
+    """Pure-null data: nothing survives, and the plot must still render."""
+    obs, _ = make_dataset(SyntheticSpec(n_seq=80, plant_fraction=0.0, seed=9))
+    result = calibrate(obs, Config(min_lag=1), null="profile", B=30, seed=2)
+    out = tmp_path / "empty.png"
+    key = support_profile(result, str(out))
+    assert out.exists()
+    assert key == [] or all(s > 0 for _, s in key)
+
+
+def test_recommend_reports_duplicates_note():
+    """recommend() surfaces same-instant duplicates as a note, not a recommendation."""
+    from tpattern import Observation, recommend
+    obs = [Observation(name=f"o{i}", start=0, end=100,
+                       events=[(0, "A"), (0, "A"), (50, "B")]) for i in range(20)]
+    rec = recommend(obs)
+    assert any("duplicate" in n.lower() for n in rec.notes), rec.notes
+    # clean data: no duplicate note
+    clean = [Observation(name=f"c{i}", start=0, end=100,
+                         events=[(0, "A"), (50, "B")]) for i in range(20)]
+    assert not any("duplicate" in n.lower() for n in recommend(clean).notes)

{tpattern-0.1.1 → tpattern-0.1.4}/tpattern/__init__.py

@@ -6,6 +6,8 @@ behavior: T-patterns and their detection. Behavior Research Methods,
 Instruments, & Computers, 32(1), 93-110.
 """
 
+__version__ = "0.1.4"   # defined before submodule imports (methods.py reads it)
+
 from .io import Observation, read_observation, read_sample, read_table
 from .pattern import Instance, Pattern
 from .ci import find_critical_interval, CIResult
@@ -13,14 +15,12 @@ from .detect import Config, Engine
 from .randomise import run_null, NullResult, rotate, shuffle
 from .significance import calibrate, CalibrationResult
 from .report import patterns_table, forest_plot, report
-from .viz import pattern_dendrogram, patterns_overview
+from .viz import pattern_dendrogram, patterns_overview, support_profile
 from .advisor import recommend
 from .methods import methods_text
 from .guided import run_analysis, launch
 from .contrast import group_contrast, contrast_items
 
-__version__ = "0.1.1"
-
 __all__ = [
     "Observation", "read_observation", "read_sample", "read_table",
     "Instance", "Pattern",
@@ -29,7 +29,7 @@ __all__ = [
     "run_null", "NullResult", "rotate", "shuffle",
     "calibrate", "CalibrationResult",
     "patterns_table", "forest_plot", "report",
-    "pattern_dendrogram", "patterns_overview",
+    "pattern_dendrogram", "patterns_overview", "support_profile",
     "recommend", "methods_text",
     "run_analysis", "launch",
     "group_contrast", "contrast_items",

{tpattern-0.1.1 → tpattern-0.1.4}/tpattern/advisor.py

@@ -47,11 +47,14 @@ class Recommendation:
     n_obs: int
     n_events: int
     choices: list[Choice]
+    notes: list[str] = field(default_factory=list)
 
     def __str__(self) -> str:
         lines = [f"Dataset: {self.n_obs} observations, {self.n_events} events\n"]
         for c in self.choices:
             lines.append(f"[{c.option}]  ->  {c.recommended}\n    {c.rationale}")
+        for n in self.notes:
+            lines.append(f"[note]  {n}")
         return "\n".join(lines)
 
     def methods_text(self) -> str:
@@ -237,5 +240,64 @@ def recommend(observations, *, min_count: int = 15,
             evidence={"threshold": threshold, "frequent": {}},
         )
 
+    # --- Minimum occurrence (detection floor; matches Config.min_occurrence) ---
+    min_occ_choice = Choice(
+        "Minimum occurrence", "3 (the field floor)",
+        rationale=("A pattern is kept only if it recurs at least this many times (default 3, the "
+                   "T-pattern convention); below three occurrences the occurrence-based surrogate "
+                   "test is too coarse to calibrate. Impact of raising it: fewer but "
+                   "better-supported patterns — it removes the near-threshold tail (which "
+                   "calibration discards anyway) and shrinks the multiple-comparison family, at "
+                   "the cost of missing genuinely rare structure. Lowering it below three is not "
+                   "recommended."),
+        plain=("<b>How many times a chain must repeat to count.</b> The default is three. "
+               "<i>Raise it</i> to report only patterns that recur often and drop rare, borderline "
+               "ones; <i>lowering</i> is not advised — two or three occurrences is already the "
+               "smallest number the chance test can judge."),
+        evidence={"min_occurrence": 3, "n_obs": n_obs},
+    )
+
+    # --- Number of surrogates B (Monte-Carlo resolution; matches calibrate's B) ---
+    B_choice = Choice(
+        "Number of surrogates (B)", "200 to screen; thousands to confirm one pattern",
+        rationale=("The Monte-Carlo empirical p-value cannot fall below 1/(B+1), so B sets the "
+                   "finest significance any single pattern can reach. B=200 is ample for "
+                   "false-discovery screening; a family-wise confirmatory claim needs 1/(B+1) "
+                   "below the family threshold alpha/m — i.e. B greater than m/alpha — which for a "
+                   "typical pattern family is in the thousands. Impact of raising B: a lower "
+                   "p-floor and a smoother empirical p, at a runtime cost that grows linearly in "
+                   "B; too small a B silently caps significance and can leave a real pattern "
+                   "unconfirmable."),
+        plain=("<b>How many reshuffled datasets to test against.</b> More surrogates give a finer, "
+               "more trustworthy p-value but are proportionally slower. <i>Use about 200</i> to "
+               "screen many patterns; <i>raise into the thousands</i> to confirm one specific "
+               "pattern, because the smallest possible p-value is 1 divided by (B+1)."),
+        evidence={"floor_at_200": 1/201, "floor_at_2000": 1/2001},
+    )
+
+    # --- diagnostic (reported, not recommended): same-instant duplicate records ---
+    notes = []
+    n_dup = 0
+    for o in observations:
+        seen = set()
+        for t, ev in o.events:
+            if (ev, t) in seen:
+                n_dup += 1
+            else:
+                seen.add((ev, t))
+    if n_dup:
+        res = _resolution_stats(observations)
+        gap = res.get("min_nonzero_gap")
+        coarse = (f" Your finest inter-event gap is {gap} time units, so if that resolution is "
+                  f"coarse for your data these may be genuinely distinct events; set "
+                  f"collapse_duplicates=False to keep them.") if gap and gap > 1 else ""
+        notes.append(
+            f"{n_dup} same-instant duplicate record(s) (same event type at an identical timestamp) "
+            f"were found and are collapsed to one point by default (collapse_duplicates): two records "
+            f"at the same instant occupy one point and retaining both would inflate that type's "
+            f"baseline rate.{coarse}")
+
     return Recommendation(n_obs=n_obs, n_events=n_events,
-                          choices=[freq_choice, null_choice, lag_choice, err_choice])
+                          choices=[freq_choice, min_occ_choice, null_choice, lag_choice,
+                                   err_choice, B_choice],
+                          notes=notes)

{tpattern-0.1.1 → tpattern-0.1.4}/tpattern/detect.py

@@ -42,17 +42,44 @@ from .pattern import Instance, Pattern
 @dataclass
 class Config:
     """Detection settings. The defaults reproduce THEME's parameters, so most users
-    change only a couple of things:
+    change only a couple of things. Every field below is user-editable; each carries
+    a mathematical reason to change it and a consequence if you do — stated here and,
+    for the data-driven ones, advised from your data by ``advisor.recommend``.
+
+    Data-driven (let ``advisor.recommend(observations)`` set these, with reasons):
 
     * ``min_lag`` — set to 1 on frame-coded data (video timestamps), where events
       sharing a timestamp are co-occurrence, not sequence. Default 0 = THEME's
-      behaviour (co-timing allowed).
-    * ``freq_exclude`` — the frequent-event exclusion (mean occurrences per
-      observation above which a type is barred from building patterns).
-
-    Not sure what to pick? ``advisor.recommend(observations)`` inspects the data and
-    suggests ``min_lag`` (and the null / error control used at ``calibrate``), with
-    the reasoning. Everything else can be left at its default.
+      behaviour. Impact: at 0, co-timed events read as directional sequences
+      (Δt = 0 has no defined order → spurious patterns); at 1 they are reported as
+      co-occurrence instead.
+    * ``freq_exclude`` — mean occurrences per observation above which a type is
+      barred from *building* patterns. Impact: raise/disable to keep a near-ubiquitous
+      connector (risking combinatorial growth of the hierarchy); lower to exclude more
+      types. The excluded type is still counted at Level 0.
+    * ``min_occurrence`` — fewest times a chain must recur to be kept. Impact: below
+      ~3 the occurrence test is too coarse to calibrate; raise it to drop the rare,
+      near-threshold tail and shrink the multiple-comparison family.
+
+    Documented defaults (sensible as-is; change only with a specific reason):
+
+    * ``alpha`` — threshold on the critical-interval binomial-tail p that accepts a
+      time window. Impact: lower → tighter, fewer windows; higher → more candidate
+      structure. Final significance comes from ``calibrate``, so this mainly ranks
+      strength, not truth.
+    * ``lumping_factor`` — treat B as part of A (and drop it from further search)
+      when the forward conditional prob N_AB/N_A exceeds this. Impact: set 0.7–1.0 on
+      dense data to bound combinatorial blow-up; None (default) keeps every pair
+      separate.
+    * ``min_samples_frac`` — a pattern must occur in at least this fraction of
+      observations (anti-monotone support; pruned during the search). Impact: set
+      (e.g. 0.1) to require patterns be widespread rather than one-offs.
+    * ``exclude_events`` — explicit include/exclude list; overrides the frequency
+      rule. Impact: force-keep a central event or force-drop a nuisance one by hand;
+      ``[]`` disables exclusion entirely.
+
+    The null and the error-rate control (FDR q-target, family-wise α) are set at
+    ``calibrate`` — see its docstring for their maths and impact.
     """
 
     alpha: float = 0.005              # Significance Level
@@ -63,11 +90,27 @@ class Config:
     #                                   a genuine temporal lag, so same-timestamp
     #                                   co-occurrences are excluded and handled
     #                                   separately as "simultaneity".
-    freq_exclude: float | None = 1.50  # auto exclude if mean/obs exceeds this
+    freq_exclude: float | None = 1.50  # auto exclude threshold; meaning depends on
+    #                                    freq_exclude_mode below
+    freq_exclude_mode: str = "per_observation"  # "per_observation" (default): exclude a
+    #   type whose MEAN OCCURRENCES PER OBSERVATION exceed freq_exclude.
+    #   "theme_sd": THEME's documented rule (Theme 6 manual, "Exclude Frequent Event
+    #   Types") -- exclude a type whose total frequency exceeds mean + x*SD of the
+    #   event-type frequency distribution, where x = freq_exclude. THEME suggests 2.5
+    #   and notes 1.5-2.5 often works. The two rules are different quantities that can
+    #   share a number, which is why a value of 1.50 does not mean the same thing in
+    #   both tools.
     exclude_events: list[str] | None = None  # explicit exclusion list (overrides
     #                                          the frequency rule when provided;
     #                                          [] disables exclusion entirely)
     include_univariate: bool = True   # Univariate Patterns = Include
+    collapse_duplicates: bool = True  # collapse same-type events sharing an identical
+    #   timestamp to one point. In the point process the detector is built on, the
+    #   unit is (type, time): two records of one type at the same instant occupy a
+    #   single point (Δt = 0, no ordering information), and retaining both inflates
+    #   N_B in the NX/T baseline without changing window occupancy. Collapsing is the
+    #   treatment consistent with that baseline; it also matches THEME's import.
+    #   (Different types at Δt = 0 are genuine co-occurrence — that is min_lag's job.)
     completeness: bool = True         # apply completeness competition
     collapse_equivalent: bool = True  # collapse occurrence-identical patterns (the
     #   two directions of a co-timed pair, or different bracketings of one chain)
@@ -85,6 +128,25 @@ class Config:
     #                                        so it is pruned during the search.
     max_level: int = 8                # safety cap on hierarchy depth
 
+    def excluded_types(self, counts: dict, n_obs: int) -> set:
+        """Which event types are barred from *building* patterns.
+
+        `counts` maps event type -> total number of occurrences. Returns the set to
+        exclude, resolving `freq_exclude_mode`.
+        """
+        if self.exclude_events is not None:
+            return set(self.exclude_events)
+        if self.freq_exclude is None or not counts:
+            return set()
+        if self.freq_exclude_mode == "theme_sd":
+            vals = list(counts.values())
+            mean = sum(vals) / len(vals)
+            var = sum((v - mean) ** 2 for v in vals) / len(vals)
+            sd = var ** 0.5
+            cut = mean + self.freq_exclude * sd
+            return {ev for ev, c in counts.items() if c > cut}
+        return {ev for ev, c in counts.items() if c / n_obs > self.freq_exclude}
+
     def is_excluded(self, event: str, mean_per_obs: float) -> bool:
         """Decide whether an event type is barred from *building* patterns.
 
@@ -135,18 +197,28 @@ class Engine:
         by_type: dict[str, list[Instance]] = defaultdict(list)
         token = 0
         for i, o in enumerate(self.obs):
+            seen_pt: set[tuple[str, int]] = set()   # (type, time) points seen in this obs
             for t, ev in o.events:
-                # Every raw event occurrence gets a globally-unique token id so
-                # that composite patterns can never reuse the same event twice.
+                if self.cfg.collapse_duplicates:
+                    # Same type at an identical timestamp = one point in the process;
+                    # keep the first, drop repeats (they add no window information and
+                    # would inflate the NX/T baseline). See Config.collapse_duplicates.
+                    if (ev, t) in seen_pt:
+                        continue
+                    seen_pt.add((ev, t))
+                # Every retained occurrence gets a globally-unique token id so that
+                # composite patterns can never reuse the same event twice.
                 by_type[ev].append(Instance(obs=i, start=t, end=t, tokens=frozenset((token,))))
                 token += 1
 
         n_obs = len(self.obs)
+        counts = {ev: len(insts) for ev, insts in by_type.items()}
+        excluded = self.cfg.excluded_types(counts, n_obs)
         self.univariate, self.terminals, self.excluded = [], [], []
         for ev, insts in sorted(by_type.items()):
             term = Pattern(event=ev, instances=insts)
             self.univariate.append(term)
-            if self.cfg.is_excluded(ev, len(insts) / n_obs):
+            if ev in excluded:
                 self.excluded.append(ev)
                 continue
             if len(insts) < self.cfg.min_occurrence:

{tpattern-0.1.1 → tpattern-0.1.4}/tpattern/methods.py

@@ -16,7 +16,7 @@ operational definition, generated from the actual `Config` that was run.
 
 from __future__ import annotations
 
-VERSION = "0.1.0"
+from . import __version__ as VERSION   # single source of truth (pyproject/__init__)
 CONCEPT_DOI = "10.5281/zenodo.21397543"
 
 
@@ -82,6 +82,11 @@ def methods_text(config, *, observations=None, calibration=None,
                  "eligible to build patterns.")
 
     # --- concurrency handling ---
+    if getattr(config, "collapse_duplicates", True):
+        s.append(
+            "Multiple records of one event type at an identical timestamp were "
+            "collapsed to a single occurrence, since they occupy one point in the "
+            "process and retaining them would inflate that type's baseline rate.")
     if getattr(config, "min_lag", 0) and config.min_lag >= 1:
         s.append(
             f"A genuine temporal gap of at least {config.min_lag} time unit(s) was "
@@ -99,10 +104,33 @@ def methods_text(config, *, observations=None, calibration=None,
     if getattr(config, "completeness", True):
         s.append("Patterns whose every occurrence was contained within a longer "
                  "detected pattern were removed (completeness competition).")
+    else:
+        s.append("Completeness competition was disabled, so patterns fully contained "
+                 "within longer ones were retained and counted separately.")
+    # These change the reported counts and the size of the multiple-comparison family,
+    # so they belong in the Methods whether or not they are left at their defaults.
+    if getattr(config, "collapse_equivalent", True):
+        s.append("Patterns sharing an identical set of occurrences (the two directions "
+                 "of a co-timed pair, or different bracketings of one chain) were "
+                 "collapsed to a single representative before counting and before "
+                 "correction, so perfectly dependent duplicates were neither reported "
+                 "nor tested twice.")
+    else:
+        s.append("Occurrence-equivalent patterns were not collapsed, so different "
+                 "bracketings of the same chain appear as separate patterns and enter "
+                 "the multiple-comparison family separately.")
+    if not getattr(config, "include_univariate", True):
+        s.append("Univariate (single-event) patterns were excluded from the output.")
     if getattr(config, "lumping_factor", None) is not None:
         s.append(f"A lumping factor of {config.lumping_factor} was applied: when a "
                  f"pair (A, B) formed with a forward conditional probability above this "
                  f"value, the dependent terminal was removed from the remaining search.")
+    if getattr(config, "max_edges", None) is not None:
+        s.append(f"The critical-interval search was capped at {config.max_edges} "
+                 f"candidate window boundaries per pair, so the window search was "
+                 f"approximate rather than exhaustive.")
+    if getattr(config, "max_level", 8) != 8:
+        s.append(f"The pattern hierarchy was capped at {config.max_level} levels.")
     if getattr(config, "min_samples_frac", None) is not None:
         s.append(f"Patterns were additionally required to occur in at least "
                  f"{config.min_samples_frac:.0%} of observations.")

{tpattern-0.1.1 → tpattern-0.1.4}/tpattern/report.py

@@ -66,23 +66,37 @@ def interpret(pattern, N, fdr_q, *, q_target=0.05, ci_unit=""):
 
 
 def patterns_table(source, outfile: str | None = None, ci_unit: str = "",
-                   sort: str = "auto"):
+                   sort: str = "auto", n_observations: int = 0):
     """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).
+
+    Every row carries `bouts` (distinct observations the pattern spans) and
+    `bout_support` (that as a fraction of the sample). Prevalence is reported rather
+    than filtered on: a reader can apply whatever support threshold they consider
+    appropriate, which a pre-applied cut-off would have denied them. Pass
+    `n_observations` to get support when `source` is a plain list of patterns.
     """
     calibrated = isinstance(source, CalibrationResult)
     items = source.real if calibrated else [p for p in source if p.level >= 1]
+    n_obs = n_observations or (source.n_observations if calibrated else 0)
 
     rows = []
     for it in items:
         p = it.pattern if calibrated else it
+        # Distinct observations (bouts) the pattern spans. N counts occurrences and
+        # can exceed this, because one bout may contain the pattern several times.
+        # Reported so prevalence is visible as a number: a reader can then apply any
+        # support threshold they wish, rather than trusting one applied for them.
+        bouts = len({inst.obs for inst in p.instances})
         row = {
             "pattern": str(p),
             "signature": p.signature(),
             "N": p.N,
+            "bouts": bouts,
+            "bout_support": round(bouts / n_obs, 4) if n_obs else None,
             "length": p.length,
             "level": p.level,
             "loop": int(p.has_loop),

{tpattern-0.1.1 → tpattern-0.1.4}/tpattern/significance.py

@@ -76,6 +76,7 @@ class CalibrationResult:
     alpha: float
     q_target: float
     null: str
+    n_observations: int = 0    # sample size, so bout support can be reported
 
     def kept(self, method: str = "fdr") -> list[Calibrated]:
         if method == "fwer":
@@ -134,10 +135,16 @@ def calibrate(observations, config: Config | None = None, *,
         "rotation"/"shuffle" are THEME-style nulls.
     B : int
         Number of surrogate datasets. The empirical p-value cannot fall below
-        1/(B+1), so family-wise (FWER) claims need B in the thousands; FDR is fine
-        at B=200.
+        1/(B+1), so family-wise (FWER) claims need B > m/alpha (m = patterns tested,
+        typically thousands); FDR is fine at B=200. Impact: too small silently caps
+        significance — a genuine pattern cannot clear the correction floor; larger B
+        gives a finer p at a runtime cost linear in B.
     alpha, q_target : float
         Family-wise level (Holm) and false-discovery target (Benjamini-Hochberg).
+        Impact: lower q_target → fewer, safer FDR survivors; lower alpha → very few
+        confirmatory FWER patterns (raise alpha to 0.05 for the conventional bar).
+        FDR flags more (a few flukes) and is for screening; FWER flags fewer, very
+        safely, and is for a single confirmatory claim.
     seed : int
         Fixes the surrogate draw, so results are reproducible.
 
@@ -215,4 +222,5 @@ def calibrate(observations, config: Config | None = None, *,
             c.fdr_q = qmap[id(c)]
 
     return CalibrationResult(real=real, surrogate_counts=surrogate_counts,
-                             B=B, alpha=alpha, q_target=q_target, null=null)
+                             B=B, alpha=alpha, q_target=q_target, null=null,
+                             n_observations=len(observations))

tpattern-0.1.4/tpattern/viz.py

@@ -0,0 +1,221 @@
+"""
+Visual output for detected T-patterns — clean, publication-ready figures.
+
+The centrepiece is `pattern_dendrogram`: a T-pattern is a binary tree of
+critical-interval links, and this draws it as a proper dendrogram — event types
+as leaves, each internal join annotated with its critical interval [d1, d2] (the
+time window within which the right side follows the left). THEME draws this as a
+cramped detection tree; here it is a clean, labelled figure.
+"""
+
+from __future__ import annotations
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+from .pattern import Pattern
+
+
+def _layout(p: Pattern, leaves: list, pos: dict):
+    """Assign (x, depth) to every node. Leaves get sequential x; internal nodes
+    sit at the mid-x of their children, depth = 1 + max child depth."""
+    if p.is_terminal:
+        x = len(leaves)
+        leaves.append(p.event)
+        pos[id(p)] = (x, 0)
+        return x, 0
+    lx, ld = _layout(p.left, leaves, pos)
+    rx, rd = _layout(p.right, leaves, pos)
+    x = (lx + rx) / 2.0
+    d = 1 + max(ld, rd)
+    pos[id(p)] = (x, d)
+    return x, d
+
+
+def _draw(p: Pattern, pos: dict, ax, ci_unit: str):
+    """Recursively draw dendrogram elbows from each internal node to its children."""
+    if p.is_terminal:
+        return
+    x, d = pos[id(p)]
+    for child in (p.left, p.right):
+        cx, cd = pos[id(child)]
+        # elbow: up from child to this node's depth, then across
+        ax.plot([cx, cx], [cd, d], color="#34495e", lw=1.4)
+        ax.plot([cx, x], [d, d], color="#34495e", lw=1.4)
+        _draw(child, pos, ax, ci_unit)
+    # annotate the critical interval on the join
+    if p.ci is not None:
+        d1, d2 = p.ci
+        ax.annotate(f"[{d1},{d2}]{ci_unit}", (x, d), textcoords="offset points",
+                    xytext=(0, 4), ha="center", fontsize=7, color="#c0392b")
+
+
+def pattern_dendrogram(pattern: Pattern, title: str | None = None,
+                       ci_unit: str = "", outfile: str | None = None, ax=None):
+    """Draw one T-pattern as a dendrogram. Returns the Axes.
+
+    Leaves (event types) are labelled along the bottom in temporal order; each
+    internal join shows its critical interval. `pattern.N` and significance can
+    be put in the title.
+    """
+    leaves: list = []
+    pos: dict = {}
+    _layout(pattern, leaves, pos)
+
+    own = ax is None
+    if own:
+        fig, ax = plt.subplots(figsize=(max(4, 1.1 * len(leaves)), 3.2))
+    _draw(pattern, pos, ax, ci_unit)
+
+    # leaf labels
+    for i, name in enumerate(leaves):
+        ax.plot([i], [0], "o", color="#2980b9", ms=6)
+        ax.annotate(name, (i, 0), textcoords="offset points", xytext=(0, -8),
+                    ha="right", va="top", rotation=35, fontsize=8)
+
+    ax.set_xlim(-0.7, len(leaves) - 0.3)
+    ax.set_ylim(-1.2, pattern.level + 0.6)
+    ax.set_yticks(range(pattern.level + 1))
+    ax.set_ylabel("level")
+    ax.set_xticks([])
+    for s in ("top", "right", "bottom"):
+        ax.spines[s].set_visible(False)
+    if title:
+        ax.set_title(title, fontsize=9, wrap=True)
+
+    if own and outfile:
+        plt.tight_layout(); plt.savefig(outfile, dpi=150); plt.close()
+    return ax
+
+
+def patterns_overview(patterns: list, outfile: str, max_rows: int = 8,
+                      ci_unit: str = "", by=lambda p: -p.N):
+    """A grid of the top pattern dendrograms (by `by`, default most frequent)."""
+    comps = sorted([p for p in patterns if p.level >= 1], key=by)[:max_rows]
+    n = len(comps)
+    if not n:
+        return
+    cols = 2
+    rows = (n + cols - 1) // cols
+    fig, axes = plt.subplots(rows, cols, figsize=(12, 3.0 * rows))
+    axes = axes.flatten() if n > 1 else [axes]
+    for ax, p in zip(axes, comps):
+        pattern_dendrogram(p, title=f"N={p.N}, level {p.level}", ci_unit=ci_unit, ax=ax)
+    for ax in axes[n:]:
+        ax.axis("off")
+    plt.tight_layout(); plt.savefig(outfile, dpi=150); plt.close()
+
+
+def support_profile(result, outfile: str, title: str | None = None,
+                    mark_thresholds=(0.10, 0.25), max_rows: int = 25,
+                    method: str = "fdr", color_by=None, highlight=None):
+    """Ranked bout-support profile of the patterns that survived calibration.
+
+    One bar per surviving pattern, ordered by the fraction of observations (bouts)
+    it spans. This reports prevalence instead of filtering on it: the reader sees
+    each pattern's spread directly and can apply whatever support threshold they
+    consider defensible.
+
+    `mark_thresholds` draws reference lines for candidate thresholds. Read them as
+    "everything below this line would be deleted", not as recommended values. A
+    knee in this profile separates common patterns from rare ones; it does NOT
+    separate real from chance, because calibration has already done that. Cutting
+    at a knee therefore removes rare patterns that are demonstrably not noise, and
+    on real data the knee ordering and the evidence ordering can disagree entirely.
+
+    Colouring the bars answers a question that generalises to any dataset: *does some
+    family of events cluster at one end of the prevalence range?* Two ways to ask it:
+
+    * ``highlight="LooseBall"`` (or a list of terms) colours every pattern whose
+      signature contains that text. No code needed, works with whatever labels your
+      own coding scheme uses.
+    * ``color_by=fn`` takes a callable mapping a signature to a group label, for
+      groupings a substring cannot express.
+
+    Leave both None for a single colour.
+
+    Returns the list of (signature, support) pairs actually plotted.
+    """
+    if color_by is None and highlight:
+        terms = [highlight] if isinstance(highlight, str) else list(highlight)
+
+        def color_by(sig, _terms=terms):
+            hit = next((t for t in _terms if t.lower() in sig.lower()), None)
+            return f"contains {hit}" if hit else "other patterns"
+
+    n_obs = getattr(result, "n_observations", 0)
+    items = []
+    for c in result.kept(method):
+        bouts = len({inst.obs for inst in c.pattern.instances})
+        items.append((c.pattern.signature(), bouts, bouts / n_obs if n_obs else 0.0))
+    items.sort(key=lambda x: -x[2])
+    shown = items[:max_rows]
+
+    n = len(shown)
+    # Long signatures are unreadable as rotated tick labels once there are more than
+    # a handful of bars, so rank-number them and let the caller print the key (the
+    # returned list) into the caption. Identity is recoverable, the shape stays clean.
+    number_bars = n > 6
+    fig, ax = plt.subplots(
+        figsize=((max(7.0, 0.42 * n + 2.2), 4.9) if number_bars
+                 else (max(6.0, 1.15 * n + 2.6), 5.2)), dpi=200)
+    if not shown:
+        ax.text(0.5, 0.5, "No pattern survived calibration,\nso there is no prevalence to report.",
+                ha="center", va="center", fontsize=10, color="#5b6270")
+        ax.axis("off")
+    else:
+        xs = range(n)
+        sup = [s for _, _, s in shown]
+        if color_by is None:
+            bar_colors = "#4a6fa5"
+        else:
+            palette = ["#4a6fa5", "#c07a3e", "#5b8c5a", "#8a6d9a"]
+            groups, seen = [], {}
+            for sig, _, _ in shown:
+                g = color_by(sig)
+                seen.setdefault(g, palette[len(seen) % len(palette)])
+                groups.append(g)
+            bar_colors = [seen[g] for g in groups]
+        bars = ax.bar(list(xs), sup, color=bar_colors, edgecolor="#2c4a72",
+                      width=0.68, zorder=3)
+        if color_by is not None:
+            from matplotlib.patches import Patch
+            ax.legend(handles=[Patch(facecolor=c, edgecolor="#2c4a72", label=g)
+                               for g, c in seen.items()],
+                      fontsize=7.4, frameon=False, loc="upper right")
+        ax.set_xticks(list(xs))
+        if number_bars:
+            ax.set_xticklabels([str(i + 1) for i in xs], fontsize=7.6)
+            ax.set_xlabel("pattern, ranked by prevalence (see caption for identities)",
+                          fontsize=8.4)
+        else:
+            ax.set_xticklabels([sig if len(sig) <= 34 else sig[:31] + "..."
+                                for sig, _, _ in shown],
+                               rotation=45, ha="right", fontsize=6.6)
+        ax.set_ylabel("bout support\n(fraction of observations the pattern appears in)",
+                      fontsize=8.4)
+        top = max(sup)
+        for i, (_, b, s) in enumerate(shown):
+            ax.text(i, s + top * 0.022, f"{s:.1%}", ha="center", va="bottom",
+                    fontsize=6.2, color="#1a1c22", zorder=4)
+        for thr in mark_thresholds or ():
+            lost = sum(1 for _, _, s in items if s < thr)
+            ax.axhline(thr, color="#b0303a", lw=1.1, ls="--", alpha=0.85, zorder=1)
+            ax.text(n - 0.4, thr, f"  {thr:.0%} would delete {lost} of {len(items)}",
+                    fontsize=6.8, color="#b0303a", va="bottom", ha="right")
+        ax.set_ylim(0, max(top * 1.30,
+                           (max(mark_thresholds) if mark_thresholds else 0) * 1.15))
+        ax.spines[["top", "right"]].set_visible(False)
+        ax.grid(axis="y", alpha=0.25, lw=0.6, zorder=0)
+        ax.yaxis.set_major_formatter(
+            matplotlib.ticker.FuncFormatter(lambda v, _: f"{v:.0%}"))
+    if title:
+        ax.set_title(title, fontsize=10.5, fontweight="bold")
+    if len(items) > max_rows:
+        fig.text(0.99, 0.005, f"showing {max_rows} of {len(items)} surviving patterns",
+                 ha="right", fontsize=6.8, color="#8a93a3")
+    fig.tight_layout()
+    fig.savefig(outfile)
+    plt.close(fig)
+    return [(sig, s) for sig, _, s in items]

{tpattern-0.1.1 → tpattern-0.1.4/tpattern.egg-info}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.1
+Version: 0.1.4
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/ajcallaway/TPattern
 Project-URL: Repository, https://github.com/ajcallaway/TPattern
 Project-URL: Archive (DOI), https://doi.org/10.5281/zenodo.21397543
@@ -15,7 +15,6 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering

{tpattern-0.1.1 → tpattern-0.1.4}/tpattern.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ tests/test_contrast.py
 tests/test_dedup.py
 tests/test_guided.py
 tests/test_reproduction.py
+tests/test_support_reporting.py
 tests/test_synthetic.py
 tpattern/__init__.py
 tpattern/advisor.py

tpattern-0.1.1/tpattern/viz.py

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