tpattern 0.1.1__tar.gz → 0.1.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.1
+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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tpattern"
-version = "0.1.1"
+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.1 → 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.1"
+__version__ = "0.1.2"
 
 __all__ = [
     "Observation", "read_observation", "read_sample", "read_table",

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

@@ -237,5 +237,41 @@ 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},
+    )
+
     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])

{tpattern-0.1.1 → 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.1 → 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.1 → tpattern-0.1.2/tpattern.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.1
+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