tpattern 0.1.0__tar.gz → 0.1.2__tar.gz

{tpattern-0.1.0/tpattern.egg-info → tpattern-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.0
+Version: 0.1.2
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
 License: MIT
@@ -75,7 +75,12 @@ model and clear reporting:
 
 ## Installation
 
-From source (until published on PyPI):
+```bash
+pip install tpattern
+```
+
+Add the guided-wizard extras with `pip install tpattern[gui]`. To work from source
+instead (for development or to run the reproduction scripts and shipped data):
 
 ```bash
 git clone https://github.com/ajcallaway/TPattern.git

{tpattern-0.1.0 → tpattern-0.1.2}/README.md

@@ -39,7 +39,12 @@ model and clear reporting:
 
 ## Installation
 
-From source (until published on PyPI):
+```bash
+pip install tpattern
+```
+
+Add the guided-wizard extras with `pip install tpattern[gui]`. To work from source
+instead (for development or to run the reproduction scripts and shipped data):
 
 ```bash
 git clone https://github.com/ajcallaway/TPattern.git

{tpattern-0.1.0 → tpattern-0.1.2}/pyproject.toml

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

{tpattern-0.1.0 → tpattern-0.1.2}/tpattern/__init__.py

@@ -19,7 +19,7 @@ from .methods import methods_text
 from .guided import run_analysis, launch
 from .contrast import group_contrast, contrast_items
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = [
     "Observation", "read_observation", "read_sample", "read_table",

{tpattern-0.1.0 → tpattern-0.1.2}/tpattern/advisor.py

@@ -191,5 +191,87 @@ def recommend(observations, *, min_count: int = 15,
         evidence={"n_obs": n_obs},
     )
 
+    # --- Frequent-event exclusion (a detection-time choice; matches Config.freq_exclude) ---
+    # A near-ubiquitous event type links to almost everything, so it acts as a universal
+    # connector and inflates the pattern hierarchy. The default excludes any type whose mean
+    # occurrences per observation exceed 1.50 from *building* patterns (they stay in Level 0).
+    # This is consequential, so the advisor surfaces it rather than leaving it a silent default.
+    threshold = 1.50
+    totals: dict[str, int] = {}
+    for o in observations:
+        for _, ev in o.events:
+            totals[ev] = totals.get(ev, 0) + 1
+    means = {ev: totals[ev] / n_obs for ev in totals} if n_obs else {}
+    frequent = sorted((ev for ev, m in means.items() if m > threshold),
+                      key=lambda e: -means[e])
+    if frequent:
+        lst = ", ".join(f"{e} ({means[e]:.2f}/obs)" for e in frequent)
+        freq_choice = Choice(
+            "Frequent-event exclusion",
+            f"exclude {len(frequent)} type(s) from pattern-building (default)",
+            rationale=(f"{len(frequent)} event type(s) occur more than {threshold} times per "
+                       f"observation on average and are excluded by default from building "
+                       f"multi-event patterns (they remain in the Level-0 univariate set): "
+                       f"{lst}. Excluding a near-ubiquitous event stops it acting as a universal "
+                       f"connector and inflating the hierarchy; retaining it "
+                       f"(Config(exclude_events=[]), or a higher freq_exclude) keeps its "
+                       f"connector patterns at the cost of combinatorial growth. Because this "
+                       f"materially changes the pattern set, it is reported here rather than "
+                       f"applied silently."),
+            plain=("<b>Very common events are set aside from pattern-building.</b> An event that "
+                   "happens many times in almost every sequence (here: " + ", ".join(frequent) +
+                   ") links to nearly everything, so leaving it in would flood the results with "
+                   "patterns that are really just 'this common event, then anything'. By default "
+                   "we keep such events in the counts but not in the built patterns. <i>Why it "
+                   "matters:</i> it keeps the patterns meaningful; if that event is central to "
+                   "your question you can choose to keep it in."),
+            evidence={"threshold": threshold, "frequent": {e: means[e] for e in frequent}},
+        )
+    else:
+        freq_choice = Choice(
+            "Frequent-event exclusion", "none needed",
+            rationale=(f"No event type exceeds {threshold} occurrences per observation on "
+                       f"average, so none is excluded from pattern-building."),
+            plain=("No single event is common enough to swamp the patterns, so every event type "
+                   "is kept in the analysis."),
+            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},
+    )
+
     return Recommendation(n_obs=n_obs, n_events=n_events,
-                          choices=[null_choice, lag_choice, err_choice])
+                          choices=[freq_choice, min_occ_choice, null_choice, lag_choice,
+                                   err_choice, B_choice])

{tpattern-0.1.0 → tpattern-0.1.2}/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

{tpattern-0.1.0 → tpattern-0.1.2}/tpattern/significance.py

@@ -134,10 +134,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.
 

{tpattern-0.1.0 → tpattern-0.1.2/tpattern.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.0
+Version: 0.1.2
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
 License: MIT
@@ -75,7 +75,12 @@ model and clear reporting:
 
 ## Installation
 
-From source (until published on PyPI):
+```bash
+pip install tpattern
+```
+
+Add the guided-wizard extras with `pip install tpattern[gui]`. To work from source
+instead (for development or to run the reproduction scripts and shipped data):
 
 ```bash
 git clone https://github.com/ajcallaway/TPattern.git