tpattern 0.1.10__tar.gz → 0.1.11__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.10
+Version: 0.1.11
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
 License-Expression: MIT

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

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

tpattern-0.1.11/tests/test_outputs.py

@@ -0,0 +1,86 @@
+"""Tests for the 0.1.11 output layer: per-pattern timing, and the THEME-style
+tables (durations, event-type roles, connections, data summary, interval counts)."""
+import os
+from tpattern import (Observation, Engine, Config, calibrate, patterns_table,
+                      duration_stats, pattern_durations, event_type_roles,
+                      connections, data_summary, interval_counts, report,
+                      occurrence_plot, duration_plot)
+
+
+def sample():
+    # A -> B at a fixed 300 ms lag in every observation; half also carry a later C, so
+    # (A B) survives standalone (not fully absorbed) alongside the longer ((A B) C).
+    obs = []
+    for i in range(8):
+        ev = [(0, "A"), (300, "B")]
+        if i < 4:
+            ev.append((600, "C"))
+        obs.append(Observation(name=f"o{i}", start=0, end=1000, events=ev))
+    return obs
+
+
+def patterns():
+    return Engine(sample(), Config(min_lag=1)).detect()
+
+
+def test_duration_stats_from_instances():
+    p = next(p for p in patterns() if p.signature() == "(A B)")
+    d = duration_stats(p)
+    assert d["n"] == 8 and d["median"] == 300 and d["min"] == 300 and d["max"] == 300
+
+
+def test_patterns_table_has_timing_columns():
+    rows = patterns_table(patterns(), n_observations=8)
+    ab = next(r for r in rows if r["signature"] == "(A B)")
+    assert ab["duration_median_ms"] == 300
+    assert ab["critical_interval"].endswith("ms")          # unit is labelled
+    assert ab["duration_range_ms"] == "[300,300]"
+
+
+def test_pattern_durations_one_row_per_occurrence():
+    rows = pattern_durations(patterns())
+    ab = [r for r in rows if r["signature"] == "(A B)"]
+    assert len(ab) == 8
+    assert all(r["duration_ms"] == r["end_ms"] - r["start_ms"] for r in rows)
+
+
+def test_event_type_roles_first_and_last():
+    roles = {r["event_type"]: r for r in event_type_roles(patterns())}
+    # A only ever starts a pattern; C only ever ends one
+    assert roles["A"]["pct_first"] == 1.0 and roles["A"]["as_last"] == 0
+    assert roles["C"]["pct_last"] == 1.0 and roles["C"]["as_first"] == 0
+
+
+def test_connections_direction():
+    conn = {r["event_type"]: r for r in connections(patterns())}
+    assert "B" in conn["A"]["followed_by"] and "C" in conn["A"]["followed_by"]
+    assert conn["A"]["n_followed_by"] >= 2
+
+
+def test_data_summary_counts():
+    rows = data_summary(sample())
+    a = next(r for r in rows if r["event_type"] == "A")
+    assert a["count"] == 8 and a["observations"] == 8 and a["mean_per_observation"] == 1.0
+
+
+def test_interval_counts_split():
+    rows = interval_counts(patterns(), [(0, 100), (100, 1000)], split_time=100)
+    ab = next(r for r in rows if r["signature"] == "(A B)")
+    # every A->B occurrence starts at t=0, so all are in [0,100] and before the split
+    assert ab["in[0,100]"] == 8 and ab["before_split"] == 8 and ab["after_split"] == 0
+
+
+def test_report_writes_all_default_outputs(tmp_path):
+    res = calibrate(sample(), Config(min_lag=1), null="profile", B=50, q_target=0.05, seed=1)
+    w = report(res, str(tmp_path), observations=sample(), title="unit test")
+    for key in ("table", "durations", "roles", "connections", "data_summary",
+                "dendrograms", "durations_plot", "occurrence_plot", "summary"):
+        assert key in w and os.path.getsize(w[key]) > 0
+
+
+def test_plots_render(tmp_path):
+    res = calibrate(sample(), Config(min_lag=1), null="profile", B=50, q_target=0.05, seed=1)
+    f1 = str(tmp_path / "occ.png"); f2 = str(tmp_path / "dur.png")
+    occurrence_plot(sample(), f1)
+    duration_plot(res, f2)
+    assert os.path.getsize(f1) > 0 and os.path.getsize(f2) > 0

{tpattern-0.1.10 → tpattern-0.1.11}/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.10"   # defined before submodule imports (methods.py reads it)
+__version__ = "0.1.11"   # defined before submodule imports (methods.py reads it)
 
 from .io import (Observation, read_observation, read_sample, read_table,
                  read_sofcoder, DataFormatError, check_reference, CHECKS)
@@ -15,9 +15,11 @@ from .ci import find_critical_interval, CIResult
 from .detect import Config, Engine
 from .randomise import run_null, NullResult, rotate, shuffle
 from .significance import calibrate, CalibrationResult, compare_nulls, NullComparison
-from .report import patterns_table, forest_plot, report
+from .report import (patterns_table, forest_plot, report, interpret, duration_stats,
+                     pattern_durations, event_type_roles, connections, data_summary,
+                     interval_counts)
 from .viz import (pattern_dendrogram, patterns_overview, support_profile,
-                  null_comparison_plot)
+                  null_comparison_plot, occurrence_plot, duration_plot, STYLE)
 from .advisor import recommend
 from .methods import methods_text
 from .guided import run_analysis, launch
@@ -31,7 +33,9 @@ __all__ = [
     "Config", "Engine",
     "run_null", "NullResult", "rotate", "shuffle",
     "calibrate", "CalibrationResult",
-    "patterns_table", "forest_plot", "report",
+    "patterns_table", "forest_plot", "report", "interpret", "duration_stats",
+    "pattern_durations", "event_type_roles", "connections", "data_summary",
+    "interval_counts", "occurrence_plot", "duration_plot", "STYLE",
     "pattern_dendrogram", "patterns_overview", "support_profile",
     "recommend", "methods_text",
     "run_analysis", "launch",

tpattern-0.1.11/tpattern/report.py

@@ -0,0 +1,405 @@
+"""
+Reporting — the output layer THEME does poorly.
+
+Three things:
+
+1. `patterns_table` — a tidy results table for detected patterns: the pattern
+   string, N, length, level, loop flag, critical interval, and (when a
+   calibration is supplied) the surrogate empirical p with **repeated-testing
+   correction** (Benjamini–Hochberg q for screening, Holm/FWER keep for
+   confirmation). Writes CSV and returns the rows.
+
+2. `forest_plot` — effect sizes with confidence intervals (odds ratios from the
+   group/outcome contrasts) as a forest plot, the standard way to show
+   which contrasts matter and how uncertain they are.
+
+3. `report` — one call that writes the table, the top-pattern dendrograms and (if
+   given) the forest plot into an output folder, so a detection run yields a
+   ready-to-read report.
+"""
+
+from __future__ import annotations
+
+import csv
+import math
+import os
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from matplotlib.transforms import blended_transform_factory
+
+import statistics as _stat
+
+from .pattern import Pattern
+from .significance import CalibrationResult, Calibrated
+from .viz import patterns_overview
+
+
+# --------------------------------------------------------------- timing / duration
+# Every pattern occurrence has a start (first event) and end (last event); their
+# difference is the occurrence's duration — for a two-event pattern that is the lag
+# from the first event to the second. THEME exposes these only as an on-demand
+# "Pattern Duration" export; here they are summarised (median and middle half) and
+# reported by default, for every pattern, so the temporal content of a T-pattern is
+# not left buried. All times are internal milliseconds (hence the `ms` unit).
+def duration_stats(pattern):
+    """Summary of a pattern's occurrence durations (end - start), or None if it has
+    no occurrences. Returns n, median, mean, q1, q3, min, max — all in ms."""
+    ds = sorted(i.end - i.start for i in pattern.instances)
+    if not ds:
+        return None
+    if len(ds) >= 4:
+        q1, med, q3 = (round(x) for x in _stat.quantiles(ds, n=4))
+    else:
+        q1, med, q3 = ds[0], round(_stat.median(ds)), ds[-1]
+    return {"n": len(ds), "median": round(_stat.median(ds)), "mean": round(_stat.mean(ds)),
+            "q1": q1, "q3": q3, "min": ds[0], "max": ds[-1]}
+
+
+def _fmt_ci(ci, unit):
+    if not ci:
+        return ""
+    return f"[{ci[0]},{ci[1]}]{unit}"
+
+
+def interpret(pattern, N, fdr_q, *, q_target=0.05, ci_unit="ms", dur=None):
+    """A plain-English reading of one calibrated pattern — what it is, whether it is
+    trustworthy, and its observed timing. Used as the results table's
+    `interpretation` column so a non-specialist can read the output directly.
+
+    `dur` is the pattern's :func:`duration_stats`; when given, the typical timing is
+    stated in words (median and middle half), which is the temporal content THEME's
+    output leaves out.
+    """
+    if fdr_q <= q_target:
+        verdict, meaning = (f"Robust (survives FDR, q={fdr_q:.3g})",
+                            "a genuine recurring sequence")
+    elif fdr_q <= 2 * q_target:
+        verdict, meaning = (f"Borderline (q={fdr_q:.3g})",
+                            "near the significance threshold — treat with caution and "
+                            "re-check with more surrogates")
+    else:
+        verdict, meaning = (f"Not significant after correction (q={fdr_q:.3g})",
+                            "consistent with chance")
+    timing = ""
+    if dur and dur["median"]:
+        lead = ("the later event follows the earlier by a median of "
+                if pattern.length == 2 else "the pattern spans a median of ")
+        timing = (f"; {lead}{dur['median']} {ci_unit} "
+                  f"(middle half {dur['q1']}–{dur['q3']}, range {dur['min']}–{dur['max']} {ci_unit})")
+    elif pattern.ci and not pattern.is_terminal:
+        d1, d2 = pattern.ci
+        timing = (f"; its components are linked within {d1}–{d2} {ci_unit}"
+                  if d1 != d2 else f"; components co-occur (0 {ci_unit} apart)")
+    loop = " (a recycling loop: a repeated event type)" if pattern.has_loop else ""
+    plural = "occurrence" if N == 1 else "occurrences"
+    return f"{verdict}: {meaning}, {N} {plural}{timing}{loop}."
+
+
+def patterns_table(source, outfile: str | None = None, ci_unit: str = "ms",
+                   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})
+        dur = duration_stats(p)
+        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),
+            "critical_interval": _fmt_ci(p.ci, ci_unit),
+            # observed timing of the occurrences (THEME's Pattern Duration, summarised
+            # and reported by default rather than left as an on-demand export)
+            "duration_median_ms": dur["median"] if dur else None,
+            "duration_iqr_ms": f"[{dur['q1']},{dur['q3']}]" if dur else None,
+            "duration_range_ms": f"[{dur['min']},{dur['max']}]" if dur else None,
+        }
+        if calibrated:
+            row["p_emp"] = round(it.p_emp, 4)
+            row["fdr_q"] = round(it.fdr_q, 4)
+            row["fwer_keep"] = int(it.fwer_keep)
+            row["analytic_strength"] = round(it.strength, 2)  # -log10(analytic p); comparison only
+            row["interpretation"] = interpret(p, it.N, it.fdr_q, ci_unit=ci_unit, dur=dur)
+        rows.append(row)
+
+    key = sort
+    if sort == "auto":
+        key = "p_emp" if calibrated else "N"
+    if key == "N":
+        rows.sort(key=lambda r: (-r["N"], r["level"]))
+    elif key in ("p_emp", "fdr_q") and calibrated:
+        rows.sort(key=lambda r: (r[key], -r["N"]))
+
+    if outfile:
+        with open(outfile, "w", newline="") as fh:
+            w = csv.DictWriter(fh, fieldnames=list(rows[0].keys()) if rows else ["pattern"])
+            w.writeheader()
+            w.writerows(rows)
+    return rows
+
+
+# --------------------------------------------------------------- forest plot
+def forest_plot(items, outfile: str, title: str = "Effect sizes (odds ratios)",
+                xlabel: str = "odds ratio (log scale)"):
+    """Forest plot of odds ratios with 95% CIs.
+
+    `items` is a list of dicts, each: {label, or, lo, hi, p (optional), n (opt)}.
+    A reference line is drawn at OR = 1. Points whose CI excludes 1 are coloured.
+    """
+    items = list(items)
+    if not items:
+        return
+    n = len(items)
+    fig, ax = plt.subplots(figsize=(9, 0.6 * n + 1.4))
+    ys = list(range(n, 0, -1))          # top-to-bottom in given order
+
+    # fix x-range up front so label anchoring is stable on the log scale.
+    # An odds-ratio CI can hit 0 or inf when a group has a zero cell, and neither
+    # is a valid limit on a log axis, so fall back to sensible finite bounds.
+    los = [it["lo"] for it in items]; his = [it["hi"] for it in items]
+    pos_lo = [x for x in los if x and x > 0]
+    fin_hi = [x for x in his if x not in (float("inf"), float("nan")) and x > 0]
+    ax.set_xscale("log")
+    ax.set_xlim((min(pos_lo) if pos_lo else 0.1) * 0.7,
+                (max(fin_hi) if fin_hi else 10.0) * 1.35)
+    ax.set_ylim(0.3, n + 0.9)
+    # label in axes-x (fixed left/right), data-y
+    tx = blended_transform_factory(ax.transAxes, ax.transData)
+
+    for y, it in zip(ys, items):
+        lo, hi, orr = it["lo"], it["hi"], it["or"]
+        sig = lo > 1 or hi < 1
+        colour = "#c0392b" if sig else "#7f8c8d"
+        ax.plot([lo, hi], [y, y], color=colour, lw=1.8, solid_capstyle="round")
+        ax.plot([orr], [y], "o", color=colour, ms=7)
+        lbl = it["label"]
+        if it.get("p") is not None:
+            lbl += f"  (p={it['p']:.3g})"
+        ax.text(0.005, y + 0.18, lbl, transform=tx, ha="left", va="bottom", fontsize=8)
+        ax.text(0.995, y, f"{orr:.2f} [{lo:.2f}, {hi:.2f}]", transform=tx,
+                ha="right", va="center", fontsize=7.5, color="#555")
+
+    ax.axvline(1.0, color="#2c3e50", lw=1.0, ls="--")
+    ax.set_yticks([])
+    ax.set_xlabel(xlabel)
+    ax.set_title(title, fontsize=11)
+    for s in ("top", "right", "left"):
+        ax.spines[s].set_visible(False)
+    plt.tight_layout(); plt.savefig(outfile, dpi=150); plt.close()
+
+
+# -------------------------------------------------- extra tables (default outputs)
+# THEME produces a menu of statistical export tables, buried under Tools -> Generate
+# Tables and off by default. These reproduce the useful ones and emit them by default,
+# because the application a user will put them to cannot be predicted and nothing that
+# could inform a reading should be hidden.
+
+def _leaves(p):
+    """Ordered event-type leaves of a pattern, left to right (temporal order)."""
+    if p.is_terminal:
+        return [p.event]
+    return _leaves(p.left) + _leaves(p.right)
+
+
+def _patterns_of(source):
+    if isinstance(source, CalibrationResult):
+        return [c.pattern for c in source.real]
+    return [p for p in source if p.level >= 1]
+
+
+def _write_csv(rows, outfile):
+    if outfile and rows:
+        with open(outfile, "w", newline="") as fh:
+            w = csv.DictWriter(fh, fieldnames=list(rows[0].keys()))
+            w.writeheader(); w.writerows(rows)
+
+
+def pattern_durations(source, outfile: str | None = None):
+    """One row per pattern *occurrence*: its observation, start, end and duration
+    (ms). This is THEME's "Pattern Duration" export, produced by default. The
+    per-pattern summary is in `patterns_table` (duration_median_ms etc.); this is the
+    raw occurrence-level table for a reader who wants the full distribution."""
+    rows = []
+    for p in _patterns_of(source):
+        for inst in p.instances:
+            rows.append({"pattern": str(p), "signature": p.signature(),
+                         "observation": inst.obs, "start_ms": inst.start,
+                         "end_ms": inst.end, "duration_ms": inst.end - inst.start})
+    rows.sort(key=lambda r: (r["signature"], r["start_ms"]))
+    _write_csv(rows, outfile)
+    return rows
+
+
+def event_type_roles(source, outfile: str | None = None):
+    """For each event type, how often it sits first, in the middle (inner) or last
+    within the detected patterns (THEME's "Event-Types in Patterns"). Counts are
+    weighted by pattern occurrences (N). Reveals, e.g., which events start chains and
+    which end them."""
+    from collections import defaultdict
+    roles = defaultdict(lambda: {"in_patterns": 0, "as_first": 0, "as_inner": 0, "as_last": 0})
+    for p in _patterns_of(source):
+        leaves = _leaves(p)
+        for i, ev in enumerate(leaves):
+            r = roles[ev]; r["in_patterns"] += p.N
+            slot = "as_first" if i == 0 else "as_last" if i == len(leaves) - 1 else "as_inner"
+            r[slot] += p.N
+    rows = []
+    for ev, r in sorted(roles.items(), key=lambda kv: -kv[1]["in_patterns"]):
+        tot = r["in_patterns"] or 1
+        rows.append({"event_type": ev, **r,
+                     "pct_first": round(r["as_first"] / tot, 3),
+                     "pct_inner": round(r["as_inner"] / tot, 3),
+                     "pct_last": round(r["as_last"] / tot, 3)})
+    _write_csv(rows, outfile)
+    return rows
+
+
+def connections(source, outfile: str | None = None):
+    """For each event type, which other types follow it within at least one detected
+    pattern, and how many distinct ones (THEME's "Connections per Event-Type"). A
+    compact 'what follows what' view of the detected structure."""
+    from collections import defaultdict
+    follows = defaultdict(set)
+    appears = defaultdict(int)
+    for p in _patterns_of(source):
+        leaves = _leaves(p)
+        for i, a in enumerate(leaves):
+            appears[a] += 1
+            for b in leaves[i + 1:]:
+                follows[a].add(b)
+    rows = [{"event_type": ev, "in_patterns": appears[ev],
+             "n_followed_by": len(follows[ev]),
+             "followed_by": ", ".join(sorted(follows[ev]))}
+            for ev in sorted(follows, key=lambda e: -len(follows[e]))]
+    _write_csv(rows, outfile)
+    return rows
+
+
+def data_summary(observations, outfile: str | None = None):
+    """Descriptive table of the input before any detection: per event type its count,
+    how many observations contain it, its mean rate per observation and share of all
+    events (THEME's event-type/overview tables). Reported so a reader can see the
+    shape of the data that produced the patterns."""
+    from collections import Counter, defaultdict
+    counts = Counter(); in_obs = defaultdict(set)
+    for o in observations:
+        for _, ev in o.events:
+            counts[ev] += 1; in_obs[ev].add(o.name)
+    n_obs = len(observations); n_ev = sum(counts.values()) or 1
+    rows = [{"event_type": ev, "count": c, "observations": len(in_obs[ev]),
+             "mean_per_observation": round(c / (n_obs or 1), 3),
+             "pct_of_events": round(c / n_ev, 4)}
+            for ev, c in counts.most_common()]
+    _write_csv(rows, outfile)
+    return rows
+
+
+def interval_counts(source, intervals, outfile: str | None = None, split_time=None):
+    """Opt-in: count each pattern's occurrences that begin within given time windows,
+    and (optionally) before vs after a split time (THEME's "Interval Counts"). Useful
+    for phase analysis, e.g. how a pattern's rate differs across halves of a session.
+    `intervals` is a list of (t1, t2) pairs in ms."""
+    rows = []
+    for p in _patterns_of(source):
+        starts = [inst.start for inst in p.instances]
+        row = {"pattern": str(p), "signature": p.signature(), "N": p.N}
+        for t1, t2 in intervals:
+            row[f"in[{t1},{t2}]"] = sum(1 for s in starts if t1 <= s <= t2)
+        if split_time is not None:
+            row["before_split"] = sum(1 for s in starts if s < split_time)
+            row["after_split"] = sum(1 for s in starts if s >= split_time)
+        rows.append(row)
+    _write_csv(rows, outfile)
+    return rows
+
+
+# ------------------------------------------------------------------- report
+def report(source, outdir: str, *, ci_unit: str = "ms", title: str = "T-pattern report",
+           effects=None, max_dendrograms: int = 8, observations=None):
+    """Write a full report to `outdir`: table (CSV), top-pattern dendrograms and,
+    if `effects` given, a forest plot. Returns paths written."""
+    os.makedirs(outdir, exist_ok=True)
+    calibrated = isinstance(source, CalibrationResult)
+    patterns = [c.pattern for c in source.real] if calibrated else \
+               [p for p in source if p.level >= 1]
+
+    written = {}
+    written["table"] = os.path.join(outdir, "patterns_table.csv")
+    rows = patterns_table(source, written["table"], ci_unit=ci_unit)
+
+    # extra default tables (nothing hidden): per-occurrence durations, event-type
+    # roles, connections, and — if the raw observations are passed — a data summary.
+    written["durations"] = os.path.join(outdir, "pattern_durations.csv")
+    pattern_durations(source, written["durations"])
+    written["roles"] = os.path.join(outdir, "event_type_roles.csv")
+    event_type_roles(source, written["roles"])
+    written["connections"] = os.path.join(outdir, "connections.csv")
+    connections(source, written["connections"])
+    if observations is not None:
+        written["data_summary"] = os.path.join(outdir, "data_summary.csv")
+        data_summary(observations, written["data_summary"])
+
+    if patterns:
+        written["dendrograms"] = os.path.join(outdir, "patterns_overview.png")
+        patterns_overview(patterns, written["dendrograms"],
+                          max_rows=max_dendrograms, ci_unit=ci_unit)
+        # temporal-signature plot: the per-occurrence duration spread per pattern
+        from .viz import duration_plot
+        written["durations_plot"] = os.path.join(outdir, "pattern_durations.png")
+        duration_plot(source, written["durations_plot"], max_rows=max_dendrograms,
+                      ci_unit=ci_unit)
+
+    if observations is not None:
+        from .viz import occurrence_plot
+        written["occurrence_plot"] = os.path.join(outdir, "event_occurrences.png")
+        occurrence_plot(observations, written["occurrence_plot"])
+
+    if effects:
+        written["forest"] = os.path.join(outdir, "effect_sizes.png")
+        forest_plot(effects, written["forest"])
+
+    # short text summary
+    written["summary"] = os.path.join(outdir, "SUMMARY.txt")
+    with open(written["summary"], "w") as fh:
+        fh.write(f"{title}\n{'=' * len(title)}\n\n")
+        fh.write(f"patterns (level >= 1): {len(patterns)}\n")
+        if calibrated:
+            kept_fdr = len(source.kept('fdr'))
+            kept_fwer = len(source.kept('fwer'))
+            fh.write(f"null: {source.null}   B={source.B}   "
+                     f"alpha={source.alpha}   q_target={source.q_target}\n")
+            fh.write(f"kept (FDR q<={source.q_target}): {kept_fdr}\n")
+            fh.write(f"kept (FWER Holm): {kept_fwer}\n")
+        fh.write("\ntop patterns:\n")
+        for r in rows[:15]:
+            line = f"  N={r['N']:>3}  L{r['level']}  {r['pattern']}"
+            if calibrated:
+                line += f"   p_emp={r['p_emp']}  q={r['fdr_q']}"
+            fh.write(line + "\n")
+    return written

{tpattern-0.1.10 → tpattern-0.1.11}/tpattern/viz.py

@@ -10,6 +10,8 @@ cramped detection tree; here it is a clean, labelled figure.
 
 from __future__ import annotations
 
+import statistics as _stat
+
 import matplotlib
 matplotlib.use("Agg")
 import matplotlib.pyplot as plt
@@ -17,6 +19,41 @@ import matplotlib.pyplot as plt
 from .pattern import Pattern
 
 
+# --------------------------------------------------------------------- styling
+# One place to change how every figure looks. Edit these values (or set them at
+# run time, e.g. `tpattern.viz.STYLE["accent"] = "#0b7285"`) to restyle all plots
+# without touching the plotting code — colours, fonts, grid and resolution are all
+# read from here. Kept deliberately small and legible so it is easy to customise.
+STYLE = {
+    "node":     "#2980b9",   # event-type leaf markers
+    "line":     "#34495e",   # dendrogram links
+    "interval": "#c0392b",   # timing annotations
+    "accent":   "#4a6fa5",   # primary bar/point colour
+    "accent2":  "#c07a3e",   # secondary group colour
+    "muted":    "#8a93a3",   # captions, secondary text
+    "text":     "#1a1c22",   # primary text
+    "grid":     "#dfe3e8",   # gridlines
+    "font_size": 8.0,
+    "title_size": 10.5,
+    "dpi": 150,
+}
+
+
+def _tidy(ax, *, grid_axis=None):
+    """Apply the shared look to an Axes: drop the top/right frame, optional soft grid."""
+    ax.spines[["top", "right"]].set_visible(False)
+    if grid_axis:
+        ax.grid(axis=grid_axis, color=STYLE["grid"], lw=0.7, zorder=0)
+    ax.tick_params(labelsize=STYLE["font_size"] - 0.5)
+    return ax
+
+
+def _median_duration(p):
+    """Median of a (sub)pattern's occurrence durations in ms, or None."""
+    ds = [i.end - i.start for i in p.instances]
+    return round(_stat.median(ds)) if ds else None
+
+
 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."""
@@ -41,14 +78,20 @@ def _draw(p: Pattern, pos: dict, ax, ci_unit: str):
     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)
+        ax.plot([cx, cx], [cd, d], color=STYLE["line"], lw=1.4)
+        ax.plot([cx, x], [d, d], color=STYLE["line"], lw=1.4)
         _draw(child, pos, ax, ci_unit)
-    # annotate the critical interval on the join
+    # annotate the join with the OBSERVED median timing (the interpretable value) and,
+    # smaller, the critical interval it was accepted within.
+    med = _median_duration(p)
+    if med is not None:
+        ax.annotate(f"~{med} {ci_unit}".strip(), (x, d), textcoords="offset points",
+                    xytext=(0, 5), ha="center", fontsize=7, fontweight="bold",
+                    color=STYLE["interval"])
     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")
+        ax.annotate(f"[{d1},{d2}]", (x, d), textcoords="offset points",
+                    xytext=(0, -9), ha="center", fontsize=6, color=STYLE["muted"])
 
 
 def pattern_dendrogram(pattern: Pattern, title: str | None = None,
@@ -70,7 +113,7 @@ def pattern_dendrogram(pattern: Pattern, title: str | None = None,
 
     # leaf labels
     for i, name in enumerate(leaves):
-        ax.plot([i], [0], "o", color="#2980b9", ms=6)
+        ax.plot([i], [0], "o", color=STYLE["node"], ms=6)
         ax.annotate(name, (i, 0), textcoords="offset points", xytext=(0, -8),
                     ha="right", va="top", rotation=35, fontsize=8)
 
@@ -274,3 +317,80 @@ def null_comparison_plot(comparison, outfile, title=None, max_rows=25):
     fig.savefig(outfile)
     plt.close(fig)
     return ordered
+
+
+def occurrence_plot(observations, outfile: str, title: str | None = None,
+                    max_types: int = 25):
+    """When does each event type happen? A strip plot of every occurrence's position
+    within its observation (0 = start of the window, 1 = end), one row per event type,
+    with the median marked. This is THEME's event-type occurrence view, and it shows
+    directly whether a type clusters early or late — the same structure the
+    conditional-uniformity diagnostic tests. Returns the event types plotted."""
+    from collections import defaultdict
+    pos = defaultdict(list)
+    for o in observations:
+        T = (o.end - o.start) or 1
+        for t, ev in o.events:
+            pos[ev].append((t - o.start) / T)
+    types = sorted(pos, key=lambda e: _stat.median(pos[e]))
+    types = types[:max_types]
+    n = len(types)
+    fig, ax = plt.subplots(figsize=(7.5, max(2.0, 0.32 * n + 1.0)), dpi=STYLE["dpi"])
+    for y, ev in enumerate(types):
+        xs = pos[ev]
+        ax.scatter(xs, [y] * len(xs), s=10, color=STYLE["accent"], alpha=0.35,
+                   edgecolors="none", zorder=2)
+        ax.plot([_stat.median(xs)], [y], "|", color=STYLE["interval"], ms=16,
+                mew=2.2, zorder=3)
+    ax.set_yticks(range(n)); ax.set_yticklabels(types, fontsize=STYLE["font_size"] - 1)
+    ax.set_xlim(-0.02, 1.02); ax.set_xlabel("position within observation (0 = start, 1 = end)",
+                                            fontsize=STYLE["font_size"])
+    ax.set_ylim(-0.6, n - 0.4)
+    _tidy(ax, grid_axis="x")
+    ax.set_title(title or "When each event type occurs", fontsize=STYLE["title_size"],
+                 fontweight="bold")
+    fig.text(0.99, 0.005, "red mark = median position", ha="right",
+             fontsize=STYLE["font_size"] - 1.5, color=STYLE["muted"])
+    fig.tight_layout(); fig.savefig(outfile); plt.close(fig)
+    return types
+
+
+def duration_plot(source, outfile: str, title: str | None = None, max_rows: int = 8,
+                  ci_unit: str = "ms"):
+    """Temporal signature of each pattern: a strip of its occurrence durations (ms),
+    one row per pattern, median marked. Turns 'N=14, q=.006' into a picture of *when*
+    the later event lands relative to the earlier. Returns the patterns plotted."""
+    from .significance import CalibrationResult
+    if isinstance(source, CalibrationResult):
+        pats = [c.pattern for c in source.real]
+    else:
+        pats = [p for p in source if p.level >= 1]
+    pats = sorted(pats, key=lambda p: -p.N)[:max_rows]
+    pats = [p for p in pats if p.instances]
+    n = len(pats)
+    if not n:
+        fig, ax = plt.subplots(figsize=(6, 2), dpi=STYLE["dpi"])
+        ax.text(0.5, 0.5, "No patterns to plot.", ha="center", va="center")
+        ax.axis("off"); fig.savefig(outfile); plt.close(fig); return []
+    fig, ax = plt.subplots(figsize=(7.5, max(2.0, 0.5 * n + 1.0)), dpi=STYLE["dpi"])
+    labels = []
+    for y, p in enumerate(pats):
+        ds = sorted(i.end - i.start for i in p.instances)
+        ax.scatter(ds, [y] * len(ds), s=22, color=STYLE["accent"], alpha=0.5,
+                   edgecolors="none", zorder=2)
+        med = _stat.median(ds)
+        ax.plot([med], [y], "|", color=STYLE["interval"], ms=18, mew=2.4, zorder=3)
+        ax.annotate(f"~{round(med)} {ci_unit}", (med, y), textcoords="offset points",
+                    xytext=(0, 7), ha="center", fontsize=STYLE["font_size"] - 1.5,
+                    color=STYLE["interval"])
+        sig = p.signature()
+        labels.append(sig if len(sig) <= 40 else sig[:37] + "...")
+    ax.set_yticks(range(n)); ax.set_yticklabels(labels, fontsize=STYLE["font_size"] - 1)
+    ax.set_ylim(-0.6, n - 0.2)
+    ax.set_xlabel(f"pattern occurrence duration ({ci_unit})", fontsize=STYLE["font_size"])
+    ax.set_xlim(left=0)
+    _tidy(ax, grid_axis="x")
+    ax.set_title(title or "Temporal signature (duration of each pattern's occurrences)",
+                 fontsize=STYLE["title_size"], fontweight="bold")
+    fig.tight_layout(); fig.savefig(outfile); plt.close(fig)
+    return pats

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.10
+Version: 0.1.11
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
 License-Expression: MIT

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

@@ -6,6 +6,7 @@ tests/test_contrast.py
 tests/test_dedup.py
 tests/test_guided.py
 tests/test_null_compare.py
+tests/test_outputs.py
 tests/test_read_table_validation.py
 tests/test_report_dendrogram.py
 tests/test_reproduction.py

tpattern-0.1.10/tpattern/report.py

@@ -1,220 +0,0 @@
-"""
-Reporting — the output layer THEME does poorly.
-
-Three things:
-
-1. `patterns_table` — a tidy results table for detected patterns: the pattern
-   string, N, length, level, loop flag, critical interval, and (when a
-   calibration is supplied) the surrogate empirical p with **repeated-testing
-   correction** (Benjamini–Hochberg q for screening, Holm/FWER keep for
-   confirmation). Writes CSV and returns the rows.
-
-2. `forest_plot` — effect sizes with confidence intervals (odds ratios from the
-   group/outcome contrasts) as a forest plot, the standard way to show
-   which contrasts matter and how uncertain they are.
-
-3. `report` — one call that writes the table, the top-pattern dendrograms and (if
-   given) the forest plot into an output folder, so a detection run yields a
-   ready-to-read report.
-"""
-
-from __future__ import annotations
-
-import csv
-import math
-import os
-
-import matplotlib
-matplotlib.use("Agg")
-import matplotlib.pyplot as plt
-from matplotlib.transforms import blended_transform_factory
-
-from .pattern import Pattern
-from .significance import CalibrationResult, Calibrated
-from .viz import patterns_overview
-
-
-# --------------------------------------------------------------------- table
-def _fmt_ci(ci, unit):
-    if not ci:
-        return ""
-    return f"[{ci[0]},{ci[1]}]{unit}"
-
-
-def interpret(pattern, N, fdr_q, *, q_target=0.05, ci_unit=""):
-    """A plain-English reading of one calibrated pattern — what it is, whether it
-    is trustworthy, and its timing. Used as the results table's `interpretation`
-    column so a non-specialist can read the output directly."""
-    if fdr_q <= q_target:
-        verdict, meaning = (f"Robust (survives FDR, q={fdr_q:.3g})",
-                            "a genuine recurring sequence")
-    elif fdr_q <= 2 * q_target:
-        verdict, meaning = (f"Borderline (q={fdr_q:.3g})",
-                            "near the significance threshold — treat with caution and "
-                            "re-check with more surrogates")
-    else:
-        verdict, meaning = (f"Not significant after correction (q={fdr_q:.3g})",
-                            "consistent with chance")
-    timing = ""
-    if pattern.ci and not pattern.is_terminal:
-        d1, d2 = pattern.ci
-        timing = (f"; its components are linked within {d1}–{d2}{ci_unit}"
-                  if d1 != d2 else f"; components co-occur (0{ci_unit} apart)")
-    loop = " (a recycling loop: a repeated event type)" if pattern.has_loop else ""
-    plural = "occurrence" if N == 1 else "occurrences"
-    return f"{verdict}: {meaning}, {N} {plural}{timing}{loop}."
-
-
-def patterns_table(source, outfile: str | None = None, ci_unit: str = "",
-                   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),
-            "critical_interval": _fmt_ci(p.ci, ci_unit),
-        }
-        if calibrated:
-            row["p_emp"] = round(it.p_emp, 4)
-            row["fdr_q"] = round(it.fdr_q, 4)
-            row["fwer_keep"] = int(it.fwer_keep)
-            row["analytic_strength"] = round(it.strength, 2)  # -log10(analytic p); comparison only
-            row["interpretation"] = interpret(p, it.N, it.fdr_q, ci_unit=ci_unit)
-        rows.append(row)
-
-    key = sort
-    if sort == "auto":
-        key = "p_emp" if calibrated else "N"
-    if key == "N":
-        rows.sort(key=lambda r: (-r["N"], r["level"]))
-    elif key in ("p_emp", "fdr_q") and calibrated:
-        rows.sort(key=lambda r: (r[key], -r["N"]))
-
-    if outfile:
-        with open(outfile, "w", newline="") as fh:
-            w = csv.DictWriter(fh, fieldnames=list(rows[0].keys()) if rows else ["pattern"])
-            w.writeheader()
-            w.writerows(rows)
-    return rows
-
-
-# --------------------------------------------------------------- forest plot
-def forest_plot(items, outfile: str, title: str = "Effect sizes (odds ratios)",
-                xlabel: str = "odds ratio (log scale)"):
-    """Forest plot of odds ratios with 95% CIs.
-
-    `items` is a list of dicts, each: {label, or, lo, hi, p (optional), n (opt)}.
-    A reference line is drawn at OR = 1. Points whose CI excludes 1 are coloured.
-    """
-    items = list(items)
-    if not items:
-        return
-    n = len(items)
-    fig, ax = plt.subplots(figsize=(9, 0.6 * n + 1.4))
-    ys = list(range(n, 0, -1))          # top-to-bottom in given order
-
-    # fix x-range up front so label anchoring is stable on the log scale.
-    # An odds-ratio CI can hit 0 or inf when a group has a zero cell, and neither
-    # is a valid limit on a log axis, so fall back to sensible finite bounds.
-    los = [it["lo"] for it in items]; his = [it["hi"] for it in items]
-    pos_lo = [x for x in los if x and x > 0]
-    fin_hi = [x for x in his if x not in (float("inf"), float("nan")) and x > 0]
-    ax.set_xscale("log")
-    ax.set_xlim((min(pos_lo) if pos_lo else 0.1) * 0.7,
-                (max(fin_hi) if fin_hi else 10.0) * 1.35)
-    ax.set_ylim(0.3, n + 0.9)
-    # label in axes-x (fixed left/right), data-y
-    tx = blended_transform_factory(ax.transAxes, ax.transData)
-
-    for y, it in zip(ys, items):
-        lo, hi, orr = it["lo"], it["hi"], it["or"]
-        sig = lo > 1 or hi < 1
-        colour = "#c0392b" if sig else "#7f8c8d"
-        ax.plot([lo, hi], [y, y], color=colour, lw=1.8, solid_capstyle="round")
-        ax.plot([orr], [y], "o", color=colour, ms=7)
-        lbl = it["label"]
-        if it.get("p") is not None:
-            lbl += f"  (p={it['p']:.3g})"
-        ax.text(0.005, y + 0.18, lbl, transform=tx, ha="left", va="bottom", fontsize=8)
-        ax.text(0.995, y, f"{orr:.2f} [{lo:.2f}, {hi:.2f}]", transform=tx,
-                ha="right", va="center", fontsize=7.5, color="#555")
-
-    ax.axvline(1.0, color="#2c3e50", lw=1.0, ls="--")
-    ax.set_yticks([])
-    ax.set_xlabel(xlabel)
-    ax.set_title(title, fontsize=11)
-    for s in ("top", "right", "left"):
-        ax.spines[s].set_visible(False)
-    plt.tight_layout(); plt.savefig(outfile, dpi=150); plt.close()
-
-
-# ------------------------------------------------------------------- report
-def report(source, outdir: str, *, ci_unit: str = "", title: str = "T-pattern report",
-           effects=None, max_dendrograms: int = 8):
-    """Write a full report to `outdir`: table (CSV), top-pattern dendrograms and,
-    if `effects` given, a forest plot. Returns paths written."""
-    os.makedirs(outdir, exist_ok=True)
-    calibrated = isinstance(source, CalibrationResult)
-    patterns = [c.pattern for c in source.real] if calibrated else \
-               [p for p in source if p.level >= 1]
-
-    written = {}
-    written["table"] = os.path.join(outdir, "patterns_table.csv")
-    rows = patterns_table(source, written["table"], ci_unit=ci_unit)
-
-    if patterns:
-        written["dendrograms"] = os.path.join(outdir, "patterns_overview.png")
-        patterns_overview(patterns, written["dendrograms"],
-                          max_rows=max_dendrograms, ci_unit=ci_unit)
-
-    if effects:
-        written["forest"] = os.path.join(outdir, "effect_sizes.png")
-        forest_plot(effects, written["forest"])
-
-    # short text summary
-    written["summary"] = os.path.join(outdir, "SUMMARY.txt")
-    with open(written["summary"], "w") as fh:
-        fh.write(f"{title}\n{'=' * len(title)}\n\n")
-        fh.write(f"patterns (level >= 1): {len(patterns)}\n")
-        if calibrated:
-            kept_fdr = len(source.kept('fdr'))
-            kept_fwer = len(source.kept('fwer'))
-            fh.write(f"null: {source.null}   B={source.B}   "
-                     f"alpha={source.alpha}   q_target={source.q_target}\n")
-            fh.write(f"kept (FDR q<={source.q_target}): {kept_fdr}\n")
-            fh.write(f"kept (FWER Holm): {kept_fwer}\n")
-        fh.write("\ntop patterns:\n")
-        for r in rows[:15]:
-            line = f"  N={r['N']:>3}  L{r['level']}  {r['pattern']}"
-            if calibrated:
-                line += f"   p_emp={r['p_emp']}  q={r['fdr_q']}"
-            fh.write(line + "\n")
-    return written