tpattern 0.1.0__py3-none-any.whl

tpattern/__init__.py

@@ -0,0 +1,36 @@
+"""tpattern — an auditable, open-source reimplementation of Magnusson's THEME
+T-pattern detection, built to reproduce (and stress-test) THEME 8 results.
+
+Reference: Magnusson, M. S. (2000). Discovering hidden time patterns in
+behavior: T-patterns and their detection. Behavior Research Methods,
+Instruments, & Computers, 32(1), 93-110.
+"""
+
+from .io import Observation, read_observation, read_sample, read_table
+from .pattern import Instance, Pattern
+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
+from .report import patterns_table, forest_plot, report
+from .viz import pattern_dendrogram, patterns_overview
+from .advisor import recommend
+from .methods import methods_text
+from .guided import run_analysis, launch
+from .contrast import group_contrast, contrast_items
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Observation", "read_observation", "read_sample", "read_table",
+    "Instance", "Pattern",
+    "find_critical_interval", "CIResult",
+    "Config", "Engine",
+    "run_null", "NullResult", "rotate", "shuffle",
+    "calibrate", "CalibrationResult",
+    "patterns_table", "forest_plot", "report",
+    "pattern_dendrogram", "patterns_overview",
+    "recommend", "methods_text",
+    "run_analysis", "launch",
+    "group_contrast", "contrast_items",
+]

tpattern/advisor.py

@@ -0,0 +1,195 @@
+"""
+Method advisor — inspect the data, recommend the choices, articulate the method.
+================================================================================
+
+The tool exposes exactly three *questions* (not tuning knobs): which null, whether
+to require a genuine lag, and which error-rate control. Rather than leave the user
+to guess (THEME's failing), the advisor measures the properties of THIS dataset
+that determine each choice, recommends one, and writes the sentence that justifies
+it — so the Methods section is generated from the data, not asserted.
+
+  1. Null (N1 rotation/shuffle vs N2 profile-preserving)
+     Driver: does each event type have its own marginal temporal profile?
+     - Measured by conditional-uniformity (KS vs Uniform of within-window
+       positions). If most types are non-uniform, marginal timing is real and
+       would masquerade as coupling under N1, so N2 is required. If types are
+       ~uniform, N1 and N2 coincide and the choice is moot.
+
+  2. Minimum lag (0 = concurrency allowed vs >=1 = genuine sequence only)
+     Driver: how often do consecutive events share a timestamp, and at what
+     resolution? A high same-unit co-occurrence fraction means within-unit order
+     is undefined, so directional patterns need a real lag.
+
+  3. Error control (FWER confirmatory vs FDR exploratory)
+     Driver: this is primarily the user's claim type, but sample size informs
+     power. We report both and recommend FDR for discovery, FWER for a small
+     number of strong confirmatory claims.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .diagnostics import within_type_diagnostics, summarise
+
+
+@dataclass
+class Choice:
+    option: str
+    recommended: str
+    rationale: str                       # technical justification (for the methods)
+    plain: str = ""                      # the same reason in plain English
+    evidence: dict = field(default_factory=dict)
+
+
+@dataclass
+class Recommendation:
+    n_obs: int
+    n_events: int
+    choices: list[Choice]
+
+    def __str__(self) -> str:
+        lines = [f"Dataset: {self.n_obs} observations, {self.n_events} events\n"]
+        for c in self.choices:
+            lines.append(f"[{c.option}]  ->  {c.recommended}\n    {c.rationale}")
+        return "\n".join(lines)
+
+    def methods_text(self) -> str:
+        """A ready-to-adapt Methods paragraph, grounded in the measured values."""
+        return " ".join(c.rationale for c in self.choices)
+
+
+def _resolution_stats(observations) -> dict:
+    """Timestamp resolution and same-unit co-occurrence rate."""
+    min_gap = None
+    same = 0
+    total = 0
+    for o in observations:
+        ts = sorted(t for t, _ in o.events)
+        for i in range(len(ts) - 1):
+            total += 1
+            d = ts[i + 1] - ts[i]
+            if d == 0:
+                same += 1
+            elif min_gap is None or d < min_gap:
+                min_gap = d
+    return {
+        "min_nonzero_gap": min_gap,
+        "same_timestamp_frac": (same / total) if total else 0.0,
+        "n_consecutive": total,
+    }
+
+
+def recommend(observations, *, min_count: int = 15,
+              uniformity_alpha: float = 0.05) -> Recommendation:
+    """Inspect the data and recommend null, min_lag and error-control, with text."""
+    n_obs = len(observations)
+    n_events = sum(len(o.events) for o in observations)
+
+    # --- Null choice: marginal temporal structure? ---
+    diag = within_type_diagnostics(observations, min_count=min_count)
+    summ = summarise(diag, alpha=uniformity_alpha)
+    frac_nu = summ.get("frac_non_uniform", 0.0)
+    # illustrative extreme (type furthest from centred placement)
+    extreme = max(diag, key=lambda d: abs(d.mean_u - 0.5), default=None)
+    ex_txt = ""
+    if extreme is not None:
+        where = "late" if extreme.mean_u > 0.5 else "early"
+        ex_txt = (f" (e.g. {extreme.event} concentrated {where} in the sequence, "
+                  f"mean position {extreme.mean_u:.2f})")
+
+    if summ["n_types_tested"] and frac_nu > 0.5:
+        null_choice = Choice(
+            "Null", "N2 profile-preserving",
+            rationale=(f"{summ['n_non_uniform']} of {summ['n_types_tested']} event "
+                       f"types deviated from uniform temporal placement "
+                       f"(KS p<{uniformity_alpha}){ex_txt}, so the profile-preserving "
+                       f"null (N2) was used to isolate cross-event coupling from each "
+                       f"type's marginal timing; the rotation null (N1) is reported "
+                       f"alongside to quantify the marginal-timing contribution."),
+            plain=("<b>Testing patterns against chance — without being fooled by "
+                   "timing.</b> Some actions naturally tend to happen at particular "
+                   "points (for example, shots come late in a move), so two actions can "
+                   "look 'linked' simply because they tend to occur at similar times — "
+                   "not because one leads to the other. To guard against this, we "
+                   "compare each of your patterns against many reshuffled copies of your "
+                   "data that keep each action's own natural timing but scramble the "
+                   "links between actions; a pattern is kept only if it happens more "
+                   "often than in those reshuffles. <i>Why it's good:</i> the patterns "
+                   "you end up with reflect genuine connections between actions, not "
+                   "accidents of timing."),
+            evidence={"frac_non_uniform": frac_nu, **summ},
+        )
+    else:
+        null_choice = Choice(
+            "Null", "N1 rotation (N2 confirms)",
+            rationale=(f"Only {summ.get('n_non_uniform',0)} of "
+                       f"{summ.get('n_types_tested',0)} event types showed marginal "
+                       f"temporal structure, so the rotation (N1) and profile-preserving "
+                       f"(N2) nulls effectively coincide; N1 was used with N2 reported "
+                       f"to confirm equivalence."),
+            plain=("How we test against chance: your actions are fairly evenly spread "
+                   "in time, so we compare each pattern to simple time-shifted copies "
+                   "of your data — a fair test when timing isn't skewed."),
+            evidence={"frac_non_uniform": frac_nu, **summ},
+        )
+
+    # --- Minimum lag: resolution and co-occurrence ---
+    res = _resolution_stats(observations)
+    stf = res["same_timestamp_frac"]
+    gap = res["min_nonzero_gap"]
+    if stf > 0.10:
+        lag_choice = Choice(
+            "Minimum lag", "min_lag = 1 (require genuine lag)",
+            rationale=(f"{stf:.0%} of consecutive events shared a timestamp at the "
+                       f"data's resolution ({gap} time-units minimum gap), so order "
+                       f"within a unit is undefined; a genuine lag was required "
+                       f"(min_lag=1) and same-unit co-occurrences were tabulated "
+                       f"separately as concurrency rather than sequence."),
+            plain=(f"<b>Is it a sequence, or two things happening at once?</b> "
+                   f"{stf:.0%} of your events share the exact same timestamp — coded at "
+                   f"the same instant (e.g. the same video frame). <i>Why this "
+                   f"matters:</i> when two actions happen at the same moment, there is no "
+                   f"way to know which came first, so treating one as a 'follow-on' from "
+                   f"the other would invent an order that isn't really in your data and "
+                   f"could turn things-happening-together into fake sequences. <i>What we "
+                   f"do:</i> we count one action as following another only when there is "
+                   f"a real gap in time between them; same-instant actions are reported "
+                   f"as happening together, not as a sequence. <i>Why it's good:</i> "
+                   f"it's a safeguard — a few apparent patterns built only on "
+                   f"same-instant events drop out (correctly, because they were never "
+                   f"sequences), so your conclusions are stronger, not weaker."),
+            evidence=res,
+        )
+    else:
+        lag_choice = Choice(
+            "Minimum lag", "min_lag = 0 (concurrency negligible)",
+            rationale=(f"Only {stf:.0%} of consecutive events shared a timestamp, so "
+                       f"concurrency is negligible and no minimum lag was imposed."),
+            plain=(f"<b>Is it a sequence, or two things happening at once?</b> Only "
+                   f"{stf:.0%} of your events share a timestamp, so their order is "
+                   f"reliable — we can trust which came first — and every event is "
+                   f"kept."),
+            evidence=res,
+        )
+
+    # --- Error control ---
+    err_choice = Choice(
+        "Error control", "FDR primary, FWER reported",
+        rationale=(f"Across {n_obs} observations, pattern significance was calibrated "
+                   f"against the null and controlled by false-discovery rate "
+                   f"(Benjamini-Hochberg, q=0.05) for discovery, with family-wise "
+                   f"control (alpha=0.005) additionally reported for confirmatory claims."),
+        plain=("<b>Guarding against false alarms.</b> When many patterns are tested at "
+               "once, some will look 'significant' just by luck. We use the "
+               "<b>false-discovery rate (FDR)</b> — a standard method that keeps the "
+               "share of these lucky flukes among your flagged results low (under 5%). "
+               "<i>Impact:</i> the patterns marked 'robust' are ones you can rely on, "
+               "not chance findings. A stricter check (the family-wise rate) is also "
+               "reported for when you want to be extra cautious about one specific "
+               "pattern."),
+        evidence={"n_obs": n_obs},
+    )
+
+    return Recommendation(n_obs=n_obs, n_events=n_events,
+                          choices=[null_choice, lag_choice, err_choice])

tpattern/ci.py

@@ -0,0 +1,300 @@
+"""
+The critical-interval (CI) test — the mathematical core.
+========================================================
+
+This is the single statistical test that the whole method is built on. It asks,
+for two patterns A and B:
+
+    "Is there a time window [d1, d2] such that, after an occurrence of A, an
+     occurrence of B follows within that window *more often than chance would
+     predict*?"
+
+If yes, (A B) is a real T-pattern and [d1, d2] is its **critical interval**.
+
+The null hypothesis (Magnusson, 2000)
+-------------------------------------
+Under H0, A and B are unrelated and B is scattered at random over the observed
+time. THEME's "NX/T" baseline states the density of B directly from the data:
+
+    p1 = N_B / T          (probability B occupies any given 1 ms time unit)
+
+    where  N_B = total occurrences of B across the whole sample
+           T   = total observed time across the whole sample (sum of windows)
+
+For a candidate window of width  w = d2 - d1 + 1  placed just after an A, the
+probability that *at least one* B lands inside it is
+
+    p_hit = 1 - (1 - p1) ** w                                            (Eq. 1)
+
+If A occurs N_A times, and the A's were unrelated to the B's, then the number k
+of A's that happen to be followed by a B in the window is Binomial(N_A, p_hit).
+So the chance of seeing k *or more* hits by luck is the upper tail
+
+    p_value = P(X >= k),   X ~ Binomial(N_A, p_hit)                      (Eq. 2)
+
+Among all windows whose p_value is below the significance level (0.005 here) and
+which contain at least `min_occurrence` hits, we keep the one capturing the
+**most occurrences** — the *largest significant* critical interval. This is
+Magnusson's notion of the critical interval: the widest window within which B
+still follows A significantly more often than chance. It yields the most
+*complete* pattern (all real instances), rather than the tightest sub-window.
+The significance test itself guards against runaway widening: a wider window has
+a higher chance baseline `p_hit`, so it can only stay significant while genuine
+hits keep pace. Ties in occurrence-count are broken toward the more significant,
+then tighter, interval.
+
+"Free" critical-interval search
+-------------------------------
+THEME offers "Fast" (d1 forced to 0, only d2 searched) and "Free" (both edges
+searched). The paper used Free, so both d1 and d2 range over the set of observed
+A→B gaps. Only real observed gaps can change k, so they are the only candidate
+edges we ever need to try — this makes the "search all windows" exact, not a
+grid approximation.
+"""
+
+from __future__ import annotations
+
+from bisect import bisect_left
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.special import betainc
+
+from .pattern import Instance, Pattern
+
+
+def binom_sf(k: int, n: int, p: float) -> float:
+    """Upper-tail binomial probability P(X >= k) for X ~ Binomial(n, p).
+
+    Uses the regularised incomplete beta identity
+        P(X >= k) = I_p(k, n - k + 1)
+    which is a single scalar C call, ~30x faster than scipy.stats.binom.sf and
+    numerically identical for our purposes.
+    """
+    if k <= 0:
+        return 1.0
+    if k > n:
+        return 0.0
+    return float(betainc(k, n - k + 1, p))
+
+
+@dataclass
+class CIResult:
+    """Outcome of a successful critical-interval search."""
+
+    d1: int
+    d2: int
+    p_value: float
+    instances: list[Instance]           # the matched (A→B) occurrences
+
+    @property
+    def N(self) -> int:
+        return len(self.instances)
+
+
+def _match_obs(a_ends, a_tok, b_ends, b_starts, b_tok, d1, d2, collect):
+    """Greedy one-to-one A→B matching within a single observation's window.
+
+    Interval-scheduling greedy: walk A's in end-time order and give each the
+    earliest still-unused B whose start lies in [a.end+d1, a.end+d2]. Every event
+    is consumed at most once (tracked with a `used` bitmask, allocation-free).
+
+    `used` bit j marks B index j taken. Because A-ends are ascending, the lower
+    scan pointer `j0` only moves forward across A's. The distinct-token check is
+    only needed when gap == 0 (a B strictly after A's end cannot share an event
+    with A); this fast-path skips the frozenset test for the common case.
+
+    If `collect` is False we only count; if True we also return the (start, end,
+    tokens) of each matched occurrence.
+    """
+    nb = len(b_starts)
+    used = 0
+    j0 = 0
+    count = 0
+    matched = [] if collect else None
+    for ai in range(len(a_ends)):
+        ae = a_ends[ai]
+        lo = ae + d1
+        hi = ae + d2
+        while j0 < nb and b_starts[j0] < lo:
+            j0 += 1
+        j = j0
+        while j < nb and b_starts[j] <= hi:
+            if not (used >> j) & 1:
+                if b_starts[j] > ae or a_tok[ai].isdisjoint(b_tok[j]):
+                    used |= 1 << j
+                    count += 1
+                    if collect:
+                        matched.append((ae, ai, j))
+                    break
+            j += 1
+    return (count, matched) if collect else count
+
+
+def find_critical_interval(
+    a: Pattern,
+    b: Pattern,
+    obs_index: dict[int, tuple],
+    total_time: int,
+    alpha: float = 0.005,
+    min_occurrence: int = 3,
+    min_lag: int = 0,
+    max_edges: int | None = None,
+) -> CIResult | None:
+    """Search for the most significant critical interval linking A then B.
+
+    Parameters
+    ----------
+    a, b : Pattern
+        The two patterns to test for an ``A -> B`` relationship.
+    obs_index : dict[obs_id -> (a_in_obs, b_in_obs)]
+        A- and B-instances grouped by observation, each list sorted by time.
+        Grouping by observation enforces that a pattern never spans two files.
+    total_time : int
+        Sum of all observation window lengths T (denominator of the baseline).
+    alpha, min_occurrence : float, int
+        THEME's Significance Level and Minimum Occurrence.
+
+    Returns
+    -------
+    CIResult | None
+        The best significant interval, or None if no window qualifies.
+    """
+    N_A = a.N
+    N_B = b.N
+    if N_A < min_occurrence or N_B < min_occurrence:
+        return None
+
+    p1 = N_B / total_time                          # NX/T baseline density
+    if p1 <= 0 or p1 >= 1:
+        return None
+    # Baseline assumptions (all standard for the analytic T-pattern test, and all
+    # relaxed by the surrogate calibration in significance.py, where this p-value
+    # serves only as a strength-ordering statistic):
+    #   * Homogeneous-Poisson null: p_hit = 1-(1-p1)^w is the discrete-Bernoulli
+    #     form of 1-exp(-p1*w); it assumes B is uniformly/independently placed.
+    #     The diagnostics module shows this is violated (events are clustered),
+    #     which is exactly why final significance is set by surrogates, not here.
+    #     NOTE ON FORM: this "NX/T" reading, 1-(1-N_B/T)^w, and Magnusson's published
+    #     form, 1-(1-w/T)^N_B, are both first-order approximations of 1-exp(-N_B*w/T)
+    #     and coincide to <=4e-4 in the pooled-millisecond regime used here (T~1e6);
+    #     they reproduce THEME's anchor counts exactly. Which form THEME uses
+    #     internally cannot be confirmed from outside.
+    #   * Independent trials: k ~ Binomial(N_A, p_hit) treats the N_A A-instances
+    #     as independent, though they share one B pool (greedy consumes B's).
+    #   * No right-censoring correction: A-instances near an observation's end
+    #     have less than a full window w available, so p_hit is a mild
+    #     over-estimate there (slightly anti-conservative).
+
+    # --- Precompute per-observation arrays once (a sorted by end, b by start) ---
+    # Also cheaply bound the maximum achievable occurrence count: in each
+    # observation at most min(#A, #B) pairs can be formed. If the sum of those
+    # caps cannot reach the minimum occurrence, no interval ever will, so we skip
+    # the whole search — this prunes the many pattern pairs that barely co-occur.
+    per_obs = []
+    a_gap_lists: list[list[int]] = []   # per A-occurrence: sorted acceptable B-gaps
+    gaps: set[int] = set()
+    max_possible = 0
+    for a_list, b_list in obs_index.values():
+        if not a_list or not b_list:
+            continue
+        a_srt = sorted(a_list, key=lambda x: x.end)
+        b_srt = sorted(b_list, key=lambda x: x.start)
+        a_ends = [x.end for x in a_srt]
+        a_tok = [x.tokens for x in a_srt]
+        a_starts = [x.start for x in a_srt]
+        b_starts = [x.start for x in b_srt]
+        b_ends = [x.end for x in b_srt]
+        b_tok = [x.tokens for x in b_srt]
+        obs_id = a_srt[0].obs
+        per_obs.append((obs_id, a_ends, a_starts, a_tok, b_ends, b_starts, b_tok))
+        max_possible += min(len(a_ends), len(b_ends))
+        for ai, ae in enumerate(a_ends):
+            row = [bs - ae for k, bs in enumerate(b_starts)
+                   if bs - ae >= min_lag and (bs > ae or a_tok[ai].isdisjoint(b_tok[k]))]
+            if row:
+                row.sort()
+                a_gap_lists.append(row)
+                gaps.update(row)
+    if max_possible < min_occurrence or not gaps:
+        return None
+    edges = sorted(gaps)
+    # For dense event streams the distinct-gap set can be enormous, making the
+    # exact O(g^2) window search costly. Optionally subsample to `max_edges`
+    # rank-spaced candidate edges (keeping the extremes) — a bounded approximation
+    # of the interval boundaries, akin to THEME's non-exhaustive "Free Heuristic".
+    if max_edges and len(edges) > max_edges:
+        step = len(edges) / max_edges
+        idx = sorted({int(i * step) for i in range(max_edges)} | {len(edges) - 1})
+        edges = [edges[i] for i in idx]
+
+    # --- Stage 1: cheap count-A upper bound. For each window, count-A = number of
+    # A-occurrences with >=1 acceptable B inside it (B reusable). Since greedy
+    # (one-to-one) can only match FEWER, count-A >= greedy_k, and significance
+    # strengthens with k, so a window that is not count-A-significant can never be
+    # greedy-significant. We collect only the count-A-significant windows as
+    # candidates — for most pattern pairs there are none, and greedy is skipped
+    # entirely. This is an exact gate, not an approximation. ---
+    candidates = []  # (countA_k, d1, d2)
+    edges_np = np.asarray(edges, dtype=np.int64)
+    for i, d1 in enumerate(edges):
+        # nearest acceptable B-gap >= d1 for each A-occurrence
+        fs = [row[j] for row in a_gap_lists
+              if (j := bisect_left(row, d1)) < len(row)]
+        if len(fs) < min_occurrence:
+            continue
+        fs_np = np.sort(np.asarray(fs, dtype=np.int64))
+        d2s = edges_np[i:]                                   # candidate right edges
+        kA = np.searchsorted(fs_np, d2s, side="right")       # count fs <= d2
+        m = kA >= min_occurrence
+        if not m.any():
+            continue
+        d2m, kAm = d2s[m], kA[m]
+        w = (d2m - d1 + 1).astype(float)
+        p_hit = 1.0 - (1.0 - p1) ** w
+        # vectorised P(X >= kA) = I_{p_hit}(kA, N_A - kA + 1)
+        pv = betainc(kAm, N_A - kAm + 1, p_hit)
+        sig = pv < alpha
+        for d2v, kAv in zip(d2m[sig].tolist(), kAm[sig].tolist()):
+            candidates.append((int(kAv), d1, int(d2v)))
+    if not candidates:
+        return None
+
+    # --- Stage 2: exact greedy only on candidate windows, largest count-A first.
+    # Once the best confirmed greedy count can't be beaten by a candidate's upper
+    # bound, stop. ---
+    candidates.sort(key=lambda c: -c[0])
+    best_key = None
+    best_d = None
+    for kA, d1, d2 in candidates:
+        if best_key is not None and kA < -best_key[0]:
+            break                        # upper bound below best greedy k → done
+        k = 0
+        for (_oid, a_ends, _as, a_tok, _be, b_starts, b_tok) in per_obs:
+            k += _match_obs(a_ends, a_tok, _be, b_starts, b_tok, d1, d2, False)
+        if k < min_occurrence:
+            continue
+        w = d2 - d1 + 1
+        p_hit = 1.0 - (1.0 - p1) ** w                      # Eq. 1
+        p_value = binom_sf(k, N_A, p_hit)                  # Eq. 2, P(X >= k)
+        if p_value >= alpha:
+            continue
+        key = (-k, p_value, w, d1)
+        if best_key is None or key < best_key:
+            best_key = key
+            best_d = (d1, d2, p_value)
+
+    if best_d is None:
+        return None
+
+    # --- Rebuild the matched occurrences for the winning window only. ---
+    d1, d2, p_value = best_d
+    instances: list[Instance] = []
+    for (oid, a_ends, a_starts, a_tok, b_ends, b_starts, b_tok) in per_obs:
+        _, matched = _match_obs(a_ends, a_tok, b_ends, b_starts, b_tok, d1, d2, True)
+        for (ae, ai, j) in matched:
+            instances.append(Instance(
+                obs=oid, start=a_starts[ai], end=b_ends[j],
+                tokens=a_tok[ai] | b_tok[j],
+            ))
+    return CIResult(d1=d1, d2=d2, p_value=p_value, instances=instances)

tpattern/contrast.py

@@ -0,0 +1,90 @@
+"""
+Group contrast — does a pattern occur more in one group than another?
+=====================================================================
+
+Promotes the recurring "winner vs loser" / "goal vs non-goal" analysis to a
+one-call library function. Detects T-patterns on the pooled sample, then for each
+pattern counts the observations in each group that contain it and tests the
+difference with Fisher's exact test and an odds ratio with a 95% confidence
+interval. The output feeds `forest_plot` directly.
+
+    from tpattern import group_contrast, forest_plot
+    rows = group_contrast(observations, group_of=winner_or_loser)
+    forest_plot(contrast_items(rows), "contrast.png")
+
+`group_of` is either a dict {observation_name: label} or a callable taking an
+Observation and returning its label. Exactly two groups are compared.
+"""
+
+from __future__ import annotations
+
+import math
+
+from .detect import Config, Engine
+
+
+def _or_ci(a, b, c, d):
+    """Odds ratio and 95% CI for the 2x2 table [[a, b], [c, d]] with a Haldane
+    +0.5 correction so zero cells don't blow up."""
+    a, b, c, d = a + 0.5, b + 0.5, c + 0.5, d + 0.5
+    orr = (a * d) / (b * c)
+    se = math.sqrt(1 / a + 1 / b + 1 / c + 1 / d)
+    return orr, math.exp(math.log(orr) - 1.96 * se), math.exp(math.log(orr) + 1.96 * se)
+
+
+def group_contrast(observations, group_of, config: Config | None = None, *,
+                   groups=None, min_count: int = 5):
+    """Compare T-pattern occurrence between two groups of observations.
+
+    Returns a list of row dicts (one per pattern), sorted by p-value, each with
+    the per-group counts, odds ratio, 95% CI, Fisher p, and which group the
+    pattern is more common in. Counts are of *observations* containing the pattern
+    at least once (not raw occurrences), so the comparison is a clean 2x2.
+    """
+    try:
+        from scipy.stats import fisher_exact
+    except ImportError as e:  # pragma: no cover
+        raise ImportError("group_contrast needs scipy") from e
+    config = config or Config()
+
+    def label(i):
+        o = observations[i]
+        return group_of(o) if callable(group_of) else group_of.get(o.name)
+
+    labels = [label(i) for i in range(len(observations))]
+    present = [g for g in dict.fromkeys(labels) if g is not None]
+    groups = groups or sorted(present, key=str)
+    if len(groups) != 2:
+        raise ValueError(f"group_contrast compares exactly two groups; found {groups}. "
+                         "Give a group_of that yields two labels (others -> None).")
+    gA, gB = groups
+    nA = sum(1 for x in labels if x == gA)
+    nB = sum(1 for x in labels if x == gB)
+    if not nA or not nB:
+        raise ValueError(f"a group is empty ({gA}: {nA}, {gB}: {nB}).")
+
+    pats = [p for p in Engine(observations, config).detect() if p.level >= 1]
+    rows = []
+    for p in pats:
+        if p.N < min_count:
+            continue
+        obs_with = {inst.obs for inst in p.instances}
+        a = sum(1 for i in obs_with if labels[i] == gA)
+        b = sum(1 for i in obs_with if labels[i] == gB)
+        orr, lo, hi = _or_ci(a, nA - a, b, nB - b)
+        _, pval = fisher_exact([[a, nA - a], [b, nB - b]])
+        rows.append({
+            "pattern": str(p), "signature": p.signature(), "N": p.N,
+            f"{gA}": f"{a}/{nA}", f"{gB}": f"{b}/{nB}",
+            "odds_ratio": round(orr, 2), "ci_low": round(lo, 2),
+            "ci_high": round(hi, 2), "p": round(pval, 4),
+            "more_common_in": gA if orr > 1 else gB,
+        })
+    rows.sort(key=lambda r: r["p"])
+    return rows
+
+
+def contrast_items(rows, top: int = 15):
+    """Turn group_contrast rows into the item list forest_plot expects."""
+    return [{"label": r["pattern"][:42], "or": r["odds_ratio"], "lo": r["ci_low"],
+             "hi": r["ci_high"], "p": r["p"]} for r in rows[:top]]