tpattern 0.1.0__py3-none-any.whl

tpattern/methods.py

@@ -0,0 +1,132 @@
+"""
+Machine-generated Methods statement — the settings *and their semantics*.
+=========================================================================
+
+The single most transparent thing an open implementation can do is state, in full,
+not only *which* settings were used but *what each one does*. Reporting a value
+("frequent-event exclusion = 1.50") does not make a result reproducible if the
+value's behaviour is hidden — two tools can read the same number and act
+differently (see the note's Section 3.1). So `methods_text()` emits a complete,
+paste-ready Methods paragraph in which every parameter is accompanied by its
+operational definition, generated from the actual `Config` that was run.
+
+    from tpattern import methods_text
+    print(methods_text(config, observations=obs, calibration=result))
+"""
+
+from __future__ import annotations
+
+VERSION = "0.1.0"
+CONCEPT_DOI = "10.5281/zenodo.21397543"
+
+
+def methods_text(config, *, observations=None, calibration=None,
+                 cite: bool = True) -> str:
+    """Return a Methods-section description of a tpattern analysis.
+
+    Every setting is stated with its operational definition, so the parameter
+    *semantics* travel with the analysis, not merely their values. Pass the
+    `observations` to include the sample size and total observation time, and a
+    `CalibrationResult` to describe the surrogate null and error control.
+    """
+    s = []
+
+    # --- provenance ---
+    if cite:
+        s.append(
+            f"T-pattern detection was performed with tpattern (v{VERSION}; "
+            f"Callaway, 2026; https://doi.org/{CONCEPT_DOI}), an open-source "
+            f"implementation of Magnusson's (2000) T-pattern algorithm.")
+    else:
+        s.append("T-pattern detection was performed with tpattern, an open-source "
+                 "implementation of Magnusson's (2000) T-pattern algorithm.")
+
+    # --- data ---
+    if observations is not None:
+        n_obs = len(observations)
+        n_ev = sum(len(o.events) for o in observations)
+        T = sum(max(o.end - o.start, 1) for o in observations)
+        s.append(f"The sample comprised {n_obs} observations containing {n_ev} "
+                 f"event occurrences over {T} time units of total observation window.")
+
+    # --- core detection ---
+    s.append(
+        f"For each ordered pair of event types (A, B), the critical interval was the "
+        f"largest time window in which B followed A more often than expected under the "
+        f"NX/T baseline, where the baseline is the probability of at least one B in a "
+        f"window of that width given B's overall rate; significance was the upper-tail "
+        f"binomial probability of the observed number of A-to-B matches, thresholded at "
+        f"α = {config.alpha}. Occurrences were matched one to one by greedy interval "
+        f"scheduling, and each event occurrence could fill at most one role within a "
+        f"pattern (distinct-token rule). Patterns were built bottom-up into a binary "
+        f"hierarchy and were required to recur at least {config.min_occurrence} times.")
+
+    # --- frequent-event exclusion (the setting whose semantics matter most) ---
+    if getattr(config, "exclude_events", None) is not None:
+        ex = config.exclude_events
+        if ex:
+            s.append(f"The following event types were excluded from pattern "
+                     f"construction (retained for baseline counts only): "
+                     f"{', '.join(ex)}.")
+        else:
+            s.append("No event types were excluded from pattern construction.")
+    elif getattr(config, "freq_exclude", None) is not None:
+        s.append(
+            f"Event types whose mean number of occurrences per observation exceeded "
+            f"{config.freq_exclude} were excluded from building patterns (the "
+            f"frequent-event exclusion); they were retained in the univariate baseline "
+            f"counts. Note that this threshold is defined on mean occurrences per "
+            f"observation.")
+    else:
+        s.append("No frequent-event exclusion was applied; all event types were "
+                 "eligible to build patterns.")
+
+    # --- concurrency handling ---
+    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 "
+            f"required between two linked events (min_lag = {config.min_lag}); events "
+            f"sharing a timestamp were therefore treated as co-occurrence and excluded "
+            f"from directional pattern detection.")
+    else:
+        s.append(
+            "Events sharing a timestamp were permitted to form directional links "
+            "(min_lag = 0); where timestamps are coarsely resolved this treats "
+            "co-timed events as ordered, and such links should be read as "
+            "co-occurrence rather than sequence.")
+
+    # --- reduction / pruning options ---
+    if getattr(config, "completeness", True):
+        s.append("Patterns whose every occurrence was contained within a longer "
+                 "detected pattern were removed (completeness competition).")
+    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, "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.")
+
+    # --- calibration / significance ---
+    if calibration is not None:
+        null_name = {"profile": "profile-preserving", "rotation": "rotation",
+                     "shuffle": "shuffling"}.get(calibration.null, calibration.null)
+        s.append(
+            f"Every detected pattern was then tested against a {null_name} surrogate "
+            f"null: {calibration.B} surrogate datasets were generated and run through "
+            f"the identical detection pipeline, giving a Monte-Carlo empirical p-value "
+            f"per pattern (so the test is automatically corrected for the selection "
+            f"over candidate intervals). Because the empirical p-value cannot fall "
+            f"below 1/({calibration.B}+1), family-wise claims require the surrogate "
+            f"count to be raised accordingly. Multiplicity was controlled by the "
+            f"Benjamini-Hochberg false-discovery rate (q ≤ {calibration.q_target}) "
+            f"and, for confirmatory claims, the Holm family-wise error rate "
+            f"(α = {calibration.alpha}), each stratified by pattern level.")
+
+    if cite:
+        s.append(
+            f"The analysis is fully reproducible from the archived software "
+            f"(https://doi.org/{CONCEPT_DOI}); the settings above, including each "
+            f"parameter's operational definition, are emitted by the software itself.")
+
+    return " ".join(s)

tpattern/pattern.py

@@ -0,0 +1,129 @@
+"""
+The T-pattern data structure.
+=============================
+
+A T-pattern is a **binary tree**. This mirrors how Magnusson (2000) builds
+patterns: never more than two things are joined at once. Bigger patterns are
+made by joining a pattern to another pattern (or single event), so the tree
+grows one critical-interval relationship at a time.
+
+    Level 0 (a "terminal"):   a single event type, e.g.  Challenge_Pressure
+    Level 1:                  (A B)         two events linked by a critical interval
+    Level 2:                  (A (B C))     an event linked to a level-1 pattern
+    ...
+
+Reading order is always left-to-right in time: in `(A B)`, every occurrence has
+an A that is *followed by* a B within the critical interval discovered for that
+link.
+
+Occurrences
+-----------
+Each pattern carries a concrete list of the times it actually happened. One
+occurrence is an :class:`Instance`: which observation it is in, and the
+[t_start, t_end] span it covers (t_start = time of the first/left-most event,
+t_end = time of the last/right-most event). The *number of occurrences* N is
+simply ``len(pattern.instances)`` — this is the N reported in the paper.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Instance:
+    """One realised occurrence of a pattern within one observation.
+
+    `tokens` holds the identities of the *distinct raw event occurrences* that
+    make up this instance. THEME requires every pattern occurrence to be built
+    from distinct events — one event may not fill two roles — so when two
+    sub-patterns are joined their token sets must be disjoint. Terminals carry a
+    single token (the event's unique id).
+    """
+
+    obs: int                    # index of the observation in the sample
+    start: int                  # time (ms) of the left-most event
+    end: int                    # time (ms) of the right-most event
+    tokens: frozenset = frozenset()
+
+
+@dataclass
+class Pattern:
+    """A node in the T-pattern tree.
+
+    A *terminal* has ``left is None and right is None`` and an ``event`` label.
+    A *composite* has ``left`` and ``right`` sub-patterns joined by the critical
+    interval ``ci = (d1, d2)`` (only meaningful for composites).
+    """
+
+    event: str | None = None                 # set only for terminals
+    left: "Pattern | None" = None
+    right: "Pattern | None" = None
+    ci: tuple[int, int] | None = None         # (d1, d2) critical interval, ms
+    p_value: float | None = None              # significance of the link
+    instances: list[Instance] = field(default_factory=list)
+
+    # ------------------------------------------------------------------ counts
+    @property
+    def N(self) -> int:
+        """Number of occurrences across the whole sample."""
+        return len(self.instances)
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.left is None and self.right is None
+
+    # ----------------------------------------------------------- tree geometry
+    def leaves(self) -> list[str]:
+        """Event types in left-to-right (temporal) order, with repeats kept."""
+        if self.is_terminal:
+            return [self.event]  # type: ignore[list-item]
+        return self.left.leaves() + self.right.leaves()
+
+    @property
+    def length(self) -> int:
+        """Pattern length = number of terminal events (THEME 'length')."""
+        return len(self.leaves())
+
+    @property
+    def level(self) -> int:
+        """Hierarchical level = tree depth. Terminals are level 0."""
+        if self.is_terminal:
+            return 0
+        return 1 + max(self.left.level, self.right.level)
+
+    @property
+    def has_loop(self) -> bool:
+        """A 'loop' is a recurrence: the same event type appears twice or more.
+
+        THEME flags these (hasloop = 1) as recycling structures — e.g. the
+        interception-mediated loops that characterise saved-shot sequences.
+        """
+        seen = self.leaves()
+        return len(set(seen)) < len(seen)
+
+    # ------------------------------------------------------------- identity/str
+    def signature(self) -> str:
+        """A canonical string that uniquely identifies the tree's *shape*.
+
+        Two patterns with the same signature are the same pattern (same events,
+        same bracketing). Used to deduplicate during detection. Critical-interval
+        widths are deliberately excluded so that the same structure discovered
+        via slightly different intervals is treated as one pattern.
+        """
+        if self.is_terminal:
+            return self.event  # type: ignore[return-value]
+        return f"({self.left.signature()} {self.right.signature()})"
+
+    def __str__(self) -> str:
+        """Human-readable rendering, e.g.  cross → (challenge → shot_goal)."""
+        if self.is_terminal:
+            return self.event  # type: ignore[return-value]
+        l, r = str(self.left), str(self.right)
+        if not self.left.is_terminal:
+            l = f"({l})"
+        if not self.right.is_terminal:
+            r = f"({r})"
+        return f"{l} → {r}"
+
+    __repr__ = __str__

tpattern/randomise.py

@@ -0,0 +1,206 @@
+"""
+Randomisation null — the Type-I-error control THEME can't easily give you.
+==========================================================================
+
+The analytic critical-interval test assumes that, under the null, the second
+event is scattered independently and uniformly. Real event streams violate that
+(events cluster, densities vary within a possession). So a pattern can clear the
+analytic 0.005 bar and still be an artefact of that clustering rather than a
+genuine temporal relationship.
+
+The fix is an *empirical* null: destroy the real cross-event timing while keeping
+each event type's own frequency and internal spacing, re-run the entire
+detection, and see which patterns still show up. A pattern that keeps appearing
+in randomised data — where by construction there is no genuine structure — is not
+trustworthy. This is exactly what makes the result defensible to a sceptical
+reviewer, and it is the honest way to decide which borderline patterns to keep.
+
+Two surrogate schemes (THEME's "Shuffling and Rotation"), 10 runs each:
+
+* Rotation  — within each observation, cyclically shift every event type's
+              time-line by its own random offset (mod window length). This keeps
+              each type's count and internal inter-event spacing intact but
+              scrambles the *relative* timing between types. It is the stricter,
+              more structure-preserving null.
+* Shuffling — within each observation, keep the set of event *times* but randomly
+              permute which event *type* sits at each time. This preserves the
+              overall event density and timing but destroys type-specific
+              temporal relationships.
+
+For each real pattern we report an empirical p-value: the fraction of surrogate
+runs in which the *same* pattern (identical signature) recurs with an occurrence
+count at least as high as observed. Empirical p = 0 means the pattern never
+arose by chance in any surrogate.
+"""
+
+from __future__ import annotations
+
+import random
+from collections import defaultdict
+from dataclasses import dataclass
+
+from .detect import Config, Engine
+from .io import Observation
+from .pattern import Pattern
+
+
+def rotate(obs: Observation, rng: random.Random) -> Observation:
+    """Rotation surrogate for one observation (per-type cyclic time shift)."""
+    T = max(obs.T, 1)
+    by_type: dict[str, list[int]] = defaultdict(list)
+    for t, ev in obs.events:
+        by_type[ev].append(t)
+    new_events: list[tuple[int, str]] = []
+    for ev, times in by_type.items():
+        offset = rng.randrange(T)
+        for t in times:
+            nt = obs.start + ((t - obs.start + offset) % T)
+            new_events.append((nt, ev))
+    new_events.sort()
+    return Observation(name=obs.name, start=obs.start, end=obs.end, events=new_events)
+
+
+def shuffle(obs: Observation, rng: random.Random) -> Observation:
+    """Shuffling surrogate for one observation (permute type labels over times)."""
+    times = [t for t, _ in obs.events]
+    types = [ev for _, ev in obs.events]
+    rng.shuffle(types)
+    new_events = sorted(zip(times, types))
+    return Observation(name=obs.name, start=obs.start, end=obs.end, events=new_events)
+
+
+def build_profiles(observations) -> dict:
+    """Pooled within-sequence position (u = (t-start)/T) for each event type.
+
+    This is each type's empirical *marginal temporal intensity* — where in a
+    sequence it tends to occur (shots late ~0.9, passes early ~0.3). It is the
+    structure the profile-preserving null keeps.
+    """
+    import numpy as np
+    pos: dict[str, list[float]] = defaultdict(list)
+    for o in observations:
+        span = max(o.end - o.start, 1)
+        for t, ev in o.events:
+            # clamp to [0, 1] so a surrogate can never be placed outside the
+            # observation window even if an event's time falls on/just past a border.
+            pos[ev].append(min(1.0, max(0.0, (t - o.start) / span)))
+    return {ev: np.asarray(v) for ev, v in pos.items()}
+
+
+def profile_surrogate(observations, profiles, rng) -> list:
+    """Profile-preserving surrogate (null N2).
+
+    For each observation and each event type, redraw that type's event times from
+    its *own* pooled marginal position profile (with replacement), keeping the
+    per-observation count. This preserves (i) each type's count per sequence and
+    (ii) each type's marginal temporal profile, while destroying any *cross-type*
+    temporal coupling. Significance against this null therefore isolates genuine
+    coordination between event types — beyond the fact that each type has its own
+    characteristic timing.
+
+    `rng` is a numpy Generator (fast vectorised sampling).
+    """
+    out = []
+    for o in observations:
+        span = max(o.end - o.start, 1)
+        counts: dict[str, int] = defaultdict(int)
+        for _, ev in o.events:
+            counts[ev] += 1
+        events: list[tuple[int, str]] = []
+        for ev, c in counts.items():
+            us = rng.choice(profiles[ev], size=c, replace=True)
+            for u in us:
+                events.append((int(round(o.start + float(u) * span)), ev))
+        events.sort()
+        out.append(Observation(name=o.name, start=o.start, end=o.end, events=events))
+    return out
+
+
+def randomise_sample(observations, method: str, rng: random.Random):
+    fn = rotate if method == "rotation" else shuffle
+    return [fn(o, rng) for o in observations]
+
+
+@dataclass
+class NullResult:
+    """Summary of the randomisation null for one detection."""
+
+    real: list[Pattern]                       # patterns detected in real data
+    runs: dict[str, list[list[Pattern]]]      # method -> list of per-run pattern lists
+    empirical_p: dict[str, float]             # real-pattern signature -> empirical p
+    n_runs_total: int
+
+    def level_counts(self):
+        """Mean number of composite patterns per level: real vs surrogate."""
+        def by_level(pats):
+            c = defaultdict(int)
+            for p in pats:
+                if p.level >= 1:
+                    c[p.level] += 1
+            return c
+
+        real_c = by_level(self.real)
+        rand_lists = [p for runs in self.runs.values() for p in runs]
+        rand_c = defaultdict(list)
+        for pats in rand_lists:
+            c = by_level(pats)
+            lv = set(c) | set(real_c)
+            for k in lv:
+                rand_c[k].append(c.get(k, 0))
+        levels = sorted(set(real_c) | set(rand_c))
+        return [
+            (lv, real_c.get(lv, 0),
+             sum(rand_c.get(lv, [])) / max(len(rand_c.get(lv, [])), 1))
+            for lv in levels
+        ]
+
+    def survivors(self, threshold: float = 0.0) -> list[Pattern]:
+        """Real composite patterns with empirical p <= threshold.
+
+        threshold = 0.0 keeps only patterns that never recurred in any surrogate
+        at equal-or-greater strength — the strictest, cleanest filter given a
+        finite number of runs.
+        """
+        return [p for p in self.real
+                if p.level >= 1 and self.empirical_p.get(p.signature(), 1.0) <= threshold]
+
+
+def run_null(observations, config: Config | None = None,
+             n_runs: int = 10, seed: int = 12345) -> NullResult:
+    """Detect on real data, then on 10 rotation + 10 shuffling surrogates."""
+    config = config or Config()
+
+    real = Engine(observations, config).detect()
+    real_index: dict[str, int] = {}
+    for p in real:
+        if p.level >= 1:
+            real_index[p.signature()] = p.N
+
+    runs: dict[str, list[list[Pattern]]] = {"rotation": [], "shuffling": []}
+    # count, per real signature, how many surrogate runs match-or-beat it
+    beat: dict[str, int] = defaultdict(int)
+
+    # fixed per-method offset — NOT hash(method), whose value is salted per Python
+    # process (PYTHONHASHSEED), which would make identical `seed` arguments produce
+    # different surrogates across runs despite the reproducibility the signature promises.
+    method_offset = {"rotation": 0, "shuffling": 1}
+    for method in ("rotation", "shuffling"):
+        for r in range(n_runs):
+            rng = random.Random((method_offset[method] * 2246822519
+                                 ^ (r * 2654435761) ^ seed) & 0xFFFFFFFF)
+            surrogate = randomise_sample(observations, method, rng)
+            pats = Engine(surrogate, config).detect()
+            runs[method].append(pats)
+            rand_best: dict[str, int] = {}
+            for p in pats:
+                if p.level >= 1:
+                    sig = p.signature()
+                    if p.N > rand_best.get(sig, 0):
+                        rand_best[sig] = p.N
+            for sig, n_real in real_index.items():
+                if rand_best.get(sig, 0) >= n_real:
+                    beat[sig] += 1
+
+    total = n_runs * 2
+    empirical_p = {sig: beat.get(sig, 0) / total for sig in real_index}
+    return NullResult(real=real, runs=runs, empirical_p=empirical_p, n_runs_total=total)

tpattern/report.py

@@ -0,0 +1,201 @@
+"""
+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"):
+    """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).
+    """
+    calibrated = isinstance(source, CalibrationResult)
+    items = source.real if calibrated else [p for p in source if p.level >= 1]
+
+    rows = []
+    for it in items:
+        p = it.pattern if calibrated else it
+        row = {
+            "pattern": str(p),
+            "signature": p.signature(),
+            "N": p.N,
+            "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
+    los = [it["lo"] for it in items]; his = [it["hi"] for it in items]
+    ax.set_xscale("log")
+    ax.set_xlim(min(los) * 0.7, max(his) * 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