tpattern 0.1.2__tar.gz → 0.1.5__tar.gz

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.2
+Version: 0.1.5
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/ajcallaway/TPattern
 Project-URL: Repository, https://github.com/ajcallaway/TPattern
 Project-URL: Archive (DOI), https://doi.org/10.5281/zenodo.21397543
@@ -15,7 +15,6 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering

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

@@ -1,14 +1,15 @@
 [build-system]
-requires = ["setuptools>=61"]
+requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "tpattern"
-version = "0.1.2"
+version = "0.1.5"
 description = "Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour"
 readme = "README.md"
 requires-python = ">=3.9"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [
     { name = "Andrew Callaway", email = "acallaway@bournemouth.ac.uk" },
 ]
@@ -20,7 +21,6 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Intended Audience :: Science/Research",
     "Topic :: Scientific/Engineering",

{tpattern-0.1.2 → tpattern-0.1.5}/tests/test_dedup.py

@@ -31,3 +31,17 @@ def test_collapse_does_not_touch_headline():
     pats = [p for p in Engine(obs, Config(min_lag=1)).detect() if p.level >= 1]
     keys = _occ_keys(pats)
     assert len(keys) == len(set(keys))  # headline path has no duplicates anyway
+
+
+def test_same_time_same_type_duplicates_collapse():
+    """Same-type events at an identical timestamp collapse to one point (default);
+    they are retained only when the option is explicitly disabled."""
+    from tpattern import Observation, Engine, Config
+    obs = [Observation(name="o", start=0, end=200,
+                       events=[(0, "A"), (0, "A"), (100, "A"), (0, "B")])]
+    eng = Engine(obs, Config()); eng.build_terminals()
+    n_A = next(p.N for p in eng.univariate if p.event == "A")
+    assert n_A == 2, f"collapse: A should be 2 distinct points, got {n_A}"
+    eng2 = Engine(obs, Config(collapse_duplicates=False)); eng2.build_terminals()
+    n_A2 = next(p.N for p in eng2.univariate if p.event == "A")
+    assert n_A2 == 3, f"no-collapse: A should retain all 3, got {n_A2}"

tpattern-0.1.5/tests/test_null_compare.py

@@ -0,0 +1,64 @@
+"""compare_nulls: profile vs rotation decomposition into core and shell."""
+import os
+
+from tpattern import (Config, compare_nulls, NullComparison, calibrate,
+                      null_comparison_plot)
+from tpattern.synthetic import SyntheticSpec, make_dataset
+
+
+def _planted(frac=0.15, seed=7):
+    # a dataset with a genuine A->B coupling planted on top of background
+    obs, _ = make_dataset(SyntheticSpec(
+        n_seq=300, planted=[("A", 0), ("B", 1500)], plant_fraction=frac,
+        jitter=200, bg_rate=2.5, seed=seed))
+    return obs
+
+
+def test_compare_nulls_structure():
+    obs = _planted()
+    cfg = Config(min_lag=1)
+    cmp = compare_nulls(obs, cfg, nulls=("profile", "rotation"), B=100, seed=1)
+    assert isinstance(cmp, NullComparison)
+    assert set(cmp.nulls) == {"profile", "rotation"}
+    # detection is null-independent: both nulls see the same detected patterns
+    assert set(cmp.detected["profile"]) == set(cmp.detected["rotation"])
+    # core is exactly the intersection of the two survivor sets
+    assert cmp.common == cmp.survives["profile"] & cmp.survives["rotation"]
+    # unique sets are disjoint from the core and from each other
+    assert cmp.unique["profile"].isdisjoint(cmp.common)
+    assert cmp.unique["rotation"].isdisjoint(cmp.common)
+    assert cmp.unique["profile"].isdisjoint(cmp.unique["rotation"])
+
+
+def test_rows_and_layers_consistent():
+    obs = _planted()
+    cmp = compare_nulls(obs, Config(min_lag=1), B=100, seed=2)
+    for r in cmp.rows():
+        surv = [n for n in cmp.nulls if r["survives"][n]]
+        assert surv, "a row must survive at least one null"
+        if len(surv) == len(cmp.nulls):
+            assert r["layer"] == "core"
+        elif len(surv) == 1:
+            assert r["layer"] == f"{surv[0]}-only"
+        # every listed q is a probability
+        for n in cmp.nulls:
+            q = r["q"][n]
+            assert q is None or 0.0 <= q <= 1.0
+
+
+def test_matches_individual_calibrate():
+    # compare_nulls must agree with calling calibrate() per null
+    obs = _planted()
+    cfg = Config(min_lag=1)
+    cmp = compare_nulls(obs, cfg, nulls=("profile", "rotation"), B=100, seed=3)
+    for null in ("profile", "rotation"):
+        r = calibrate(obs, cfg, null=null, B=100, seed=3)
+        assert cmp.survives[null] == {c.pattern.signature() for c in r.kept("fdr")}
+
+
+def test_plot_writes_file(tmp_path):
+    obs = _planted()
+    cmp = compare_nulls(obs, Config(min_lag=1), B=100, seed=4)
+    out = tmp_path / "cmp.png"
+    null_comparison_plot(cmp, str(out), title="test")
+    assert out.exists() and out.stat().st_size > 0

tpattern-0.1.5/tests/test_support_reporting.py

@@ -0,0 +1,84 @@
+"""Bout support is *reported*, not filtered on.
+
+The support threshold (`min_samples_frac`) is a prevalence filter, not a
+significance test, so the library's job is to make prevalence visible rather than
+to cut on it. These tests pin that contract: every results row carries the number
+of distinct bouts and the support fraction, and the profile plot renders from a
+calibration result.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from tpattern import (Config, Engine, calibrate, patterns_table,  # noqa: E402
+                      support_profile)
+from tpattern.synthetic import SyntheticSpec, make_dataset  # noqa: E402
+
+
+def _sample():
+    spec = SyntheticSpec(n_seq=120, planted=[("A", 0), ("B", 1500)],
+                         plant_fraction=0.35, seed=5)
+    obs, truth = make_dataset(spec)
+    return obs, truth
+
+
+def test_table_reports_bouts_and_support():
+    obs, _ = _sample()
+    result = calibrate(obs, Config(min_lag=1), null="profile", B=30, seed=1)
+    rows = patterns_table(result)
+    assert rows, "expected at least one detected pattern"
+    for row in rows:
+        # bouts counts DISTINCT observations; N counts occurrences and may exceed it
+        assert 1 <= row["bouts"] <= len(obs)
+        assert row["bouts"] <= row["N"]
+        assert 0.0 < row["bout_support"] <= 1.0
+        assert abs(row["bout_support"] - row["bouts"] / len(obs)) < 1e-6
+
+
+def test_support_needs_sample_size_when_uncalibrated():
+    """A plain pattern list has no sample size, so support is None unless given."""
+    obs, _ = _sample()
+    pats = [p for p in Engine(obs, Config(min_lag=1)).detect() if p.level >= 1]
+    assert patterns_table(pats)[0]["bout_support"] is None
+    rows = patterns_table(pats, n_observations=len(obs))
+    assert rows[0]["bout_support"] is not None
+
+
+def test_calibration_result_carries_sample_size():
+    obs, _ = _sample()
+    result = calibrate(obs, Config(min_lag=1), null="profile", B=30, seed=1)
+    assert result.n_observations == len(obs)
+
+
+def test_support_profile_renders(tmp_path):
+    obs, _ = _sample()
+    result = calibrate(obs, Config(min_lag=1), null="profile", B=30, seed=1)
+    out = tmp_path / "profile.png"
+    key = support_profile(result, str(out), mark_thresholds=(0.10,))
+    assert out.exists() and out.stat().st_size > 0
+    # returned key is ordered by descending support, so a caption can be built from it
+    assert key == sorted(key, key=lambda kv: -kv[1])
+
+
+def test_support_profile_handles_no_survivors(tmp_path):
+    """Pure-null data: nothing survives, and the plot must still render."""
+    obs, _ = make_dataset(SyntheticSpec(n_seq=80, plant_fraction=0.0, seed=9))
+    result = calibrate(obs, Config(min_lag=1), null="profile", B=30, seed=2)
+    out = tmp_path / "empty.png"
+    key = support_profile(result, str(out))
+    assert out.exists()
+    assert key == [] or all(s > 0 for _, s in key)
+
+
+def test_recommend_reports_duplicates_note():
+    """recommend() surfaces same-instant duplicates as a note, not a recommendation."""
+    from tpattern import Observation, recommend
+    obs = [Observation(name=f"o{i}", start=0, end=100,
+                       events=[(0, "A"), (0, "A"), (50, "B")]) for i in range(20)]
+    rec = recommend(obs)
+    assert any("duplicate" in n.lower() for n in rec.notes), rec.notes
+    # clean data: no duplicate note
+    clean = [Observation(name=f"c{i}", start=0, end=100,
+                         events=[(0, "A"), (50, "B")]) for i in range(20)]
+    assert not any("duplicate" in n.lower() for n in recommend(clean).notes)

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

@@ -6,21 +6,22 @@ behavior: T-patterns and their detection. Behavior Research Methods,
 Instruments, & Computers, 32(1), 93-110.
 """
 
+__version__ = "0.1.5"   # defined before submodule imports (methods.py reads it)
+
 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 .significance import calibrate, CalibrationResult, compare_nulls, NullComparison
 from .report import patterns_table, forest_plot, report
-from .viz import pattern_dendrogram, patterns_overview
+from .viz import (pattern_dendrogram, patterns_overview, support_profile,
+                  null_comparison_plot)
 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.2"
-
 __all__ = [
     "Observation", "read_observation", "read_sample", "read_table",
     "Instance", "Pattern",
@@ -29,7 +30,7 @@ __all__ = [
     "run_null", "NullResult", "rotate", "shuffle",
     "calibrate", "CalibrationResult",
     "patterns_table", "forest_plot", "report",
-    "pattern_dendrogram", "patterns_overview",
+    "pattern_dendrogram", "patterns_overview", "support_profile",
     "recommend", "methods_text",
     "run_analysis", "launch",
     "group_contrast", "contrast_items",

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

@@ -47,11 +47,14 @@ class Recommendation:
     n_obs: int
     n_events: int
     choices: list[Choice]
+    notes: list[str] = field(default_factory=list)
 
     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}")
+        for n in self.notes:
+            lines.append(f"[note]  {n}")
         return "\n".join(lines)
 
     def methods_text(self) -> str:
@@ -106,7 +109,12 @@ def recommend(observations, *, min_count: int = 15,
                        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."),
+                       f"alongside to quantify the marginal-timing contribution. The "
+                       f"two nulls also pose different questions: N1 tests whether any "
+                       f"temporal structure is present, N2 whether events are coupled "
+                       f"beyond their own timing (the usual T-pattern claim), so N2 is "
+                       f"recommended here; choose N1 if your question is only whether "
+                       f"structure exists."),
             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 "
@@ -272,6 +280,29 @@ def recommend(observations, *, min_count: int = 15,
         evidence={"floor_at_200": 1/201, "floor_at_2000": 1/2001},
     )
 
+    # --- diagnostic (reported, not recommended): same-instant duplicate records ---
+    notes = []
+    n_dup = 0
+    for o in observations:
+        seen = set()
+        for t, ev in o.events:
+            if (ev, t) in seen:
+                n_dup += 1
+            else:
+                seen.add((ev, t))
+    if n_dup:
+        res = _resolution_stats(observations)
+        gap = res.get("min_nonzero_gap")
+        coarse = (f" Your finest inter-event gap is {gap} time units, so if that resolution is "
+                  f"coarse for your data these may be genuinely distinct events; set "
+                  f"collapse_duplicates=False to keep them.") if gap and gap > 1 else ""
+        notes.append(
+            f"{n_dup} same-instant duplicate record(s) (same event type at an identical timestamp) "
+            f"were found and are collapsed to one point by default (collapse_duplicates): two records "
+            f"at the same instant occupy one point and retaining both would inflate that type's "
+            f"baseline rate.{coarse}")
+
     return Recommendation(n_obs=n_obs, n_events=n_events,
                           choices=[freq_choice, min_occ_choice, null_choice, lag_choice,
-                                   err_choice, B_choice])
+                                   err_choice, B_choice],
+                          notes=notes)

{tpattern-0.1.2 → tpattern-0.1.5}/tpattern/detect.py

@@ -90,11 +90,27 @@ class Config:
     #                                   a genuine temporal lag, so same-timestamp
     #                                   co-occurrences are excluded and handled
     #                                   separately as "simultaneity".
-    freq_exclude: float | None = 1.50  # auto exclude if mean/obs exceeds this
+    freq_exclude: float | None = 1.50  # auto exclude threshold; meaning depends on
+    #                                    freq_exclude_mode below
+    freq_exclude_mode: str = "per_observation"  # "per_observation" (default): exclude a
+    #   type whose MEAN OCCURRENCES PER OBSERVATION exceed freq_exclude.
+    #   "theme_sd": THEME's documented rule (Theme 6 manual, "Exclude Frequent Event
+    #   Types") -- exclude a type whose total frequency exceeds mean + x*SD of the
+    #   event-type frequency distribution, where x = freq_exclude. THEME suggests 2.5
+    #   and notes 1.5-2.5 often works. The two rules are different quantities that can
+    #   share a number, which is why a value of 1.50 does not mean the same thing in
+    #   both tools.
     exclude_events: list[str] | None = None  # explicit exclusion list (overrides
     #                                          the frequency rule when provided;
     #                                          [] disables exclusion entirely)
     include_univariate: bool = True   # Univariate Patterns = Include
+    collapse_duplicates: bool = True  # collapse same-type events sharing an identical
+    #   timestamp to one point. In the point process the detector is built on, the
+    #   unit is (type, time): two records of one type at the same instant occupy a
+    #   single point (Δt = 0, no ordering information), and retaining both inflates
+    #   N_B in the NX/T baseline without changing window occupancy. Collapsing is the
+    #   treatment consistent with that baseline; it also matches THEME's import.
+    #   (Different types at Δt = 0 are genuine co-occurrence — that is min_lag's job.)
     completeness: bool = True         # apply completeness competition
     collapse_equivalent: bool = True  # collapse occurrence-identical patterns (the
     #   two directions of a co-timed pair, or different bracketings of one chain)
@@ -112,6 +128,25 @@ class Config:
     #                                        so it is pruned during the search.
     max_level: int = 8                # safety cap on hierarchy depth
 
+    def excluded_types(self, counts: dict, n_obs: int) -> set:
+        """Which event types are barred from *building* patterns.
+
+        `counts` maps event type -> total number of occurrences. Returns the set to
+        exclude, resolving `freq_exclude_mode`.
+        """
+        if self.exclude_events is not None:
+            return set(self.exclude_events)
+        if self.freq_exclude is None or not counts:
+            return set()
+        if self.freq_exclude_mode == "theme_sd":
+            vals = list(counts.values())
+            mean = sum(vals) / len(vals)
+            var = sum((v - mean) ** 2 for v in vals) / len(vals)
+            sd = var ** 0.5
+            cut = mean + self.freq_exclude * sd
+            return {ev for ev, c in counts.items() if c > cut}
+        return {ev for ev, c in counts.items() if c / n_obs > self.freq_exclude}
+
     def is_excluded(self, event: str, mean_per_obs: float) -> bool:
         """Decide whether an event type is barred from *building* patterns.
 
@@ -162,18 +197,28 @@ class Engine:
         by_type: dict[str, list[Instance]] = defaultdict(list)
         token = 0
         for i, o in enumerate(self.obs):
+            seen_pt: set[tuple[str, int]] = set()   # (type, time) points seen in this obs
             for t, ev in o.events:
-                # Every raw event occurrence gets a globally-unique token id so
-                # that composite patterns can never reuse the same event twice.
+                if self.cfg.collapse_duplicates:
+                    # Same type at an identical timestamp = one point in the process;
+                    # keep the first, drop repeats (they add no window information and
+                    # would inflate the NX/T baseline). See Config.collapse_duplicates.
+                    if (ev, t) in seen_pt:
+                        continue
+                    seen_pt.add((ev, t))
+                # Every retained occurrence gets a globally-unique token id so that
+                # composite patterns can never reuse the same event twice.
                 by_type[ev].append(Instance(obs=i, start=t, end=t, tokens=frozenset((token,))))
                 token += 1
 
         n_obs = len(self.obs)
+        counts = {ev: len(insts) for ev, insts in by_type.items()}
+        excluded = self.cfg.excluded_types(counts, n_obs)
         self.univariate, self.terminals, self.excluded = [], [], []
         for ev, insts in sorted(by_type.items()):
             term = Pattern(event=ev, instances=insts)
             self.univariate.append(term)
-            if self.cfg.is_excluded(ev, len(insts) / n_obs):
+            if ev in excluded:
                 self.excluded.append(ev)
                 continue
             if len(insts) < self.cfg.min_occurrence:

{tpattern-0.1.2 → tpattern-0.1.5}/tpattern/methods.py

@@ -16,7 +16,7 @@ operational definition, generated from the actual `Config` that was run.
 
 from __future__ import annotations
 
-VERSION = "0.1.0"
+from . import __version__ as VERSION   # single source of truth (pyproject/__init__)
 CONCEPT_DOI = "10.5281/zenodo.21397543"
 
 
@@ -82,6 +82,11 @@ def methods_text(config, *, observations=None, calibration=None,
                  "eligible to build patterns.")
 
     # --- concurrency handling ---
+    if getattr(config, "collapse_duplicates", True):
+        s.append(
+            "Multiple records of one event type at an identical timestamp were "
+            "collapsed to a single occurrence, since they occupy one point in the "
+            "process and retaining them would inflate that type's baseline rate.")
     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 "
@@ -99,10 +104,33 @@ def methods_text(config, *, observations=None, calibration=None,
     if getattr(config, "completeness", True):
         s.append("Patterns whose every occurrence was contained within a longer "
                  "detected pattern were removed (completeness competition).")
+    else:
+        s.append("Completeness competition was disabled, so patterns fully contained "
+                 "within longer ones were retained and counted separately.")
+    # These change the reported counts and the size of the multiple-comparison family,
+    # so they belong in the Methods whether or not they are left at their defaults.
+    if getattr(config, "collapse_equivalent", True):
+        s.append("Patterns sharing an identical set of occurrences (the two directions "
+                 "of a co-timed pair, or different bracketings of one chain) were "
+                 "collapsed to a single representative before counting and before "
+                 "correction, so perfectly dependent duplicates were neither reported "
+                 "nor tested twice.")
+    else:
+        s.append("Occurrence-equivalent patterns were not collapsed, so different "
+                 "bracketings of the same chain appear as separate patterns and enter "
+                 "the multiple-comparison family separately.")
+    if not getattr(config, "include_univariate", True):
+        s.append("Univariate (single-event) patterns were excluded from the output.")
     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, "max_edges", None) is not None:
+        s.append(f"The critical-interval search was capped at {config.max_edges} "
+                 f"candidate window boundaries per pair, so the window search was "
+                 f"approximate rather than exhaustive.")
+    if getattr(config, "max_level", 8) != 8:
+        s.append(f"The pattern hierarchy was capped at {config.max_level} levels.")
     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.")

{tpattern-0.1.2 → tpattern-0.1.5}/tpattern/report.py

@@ -66,23 +66,37 @@ def interpret(pattern, N, fdr_q, *, q_target=0.05, ci_unit=""):
 
 
 def patterns_table(source, outfile: str | None = None, ci_unit: str = "",
-                   sort: str = "auto"):
+                   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),

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

@@ -76,6 +76,7 @@ class CalibrationResult:
     alpha: float
     q_target: float
     null: str
+    n_observations: int = 0    # sample size, so bout support can be reported
 
     def kept(self, method: str = "fdr") -> list[Calibrated]:
         if method == "fwer":
@@ -221,4 +222,123 @@ def calibrate(observations, config: Config | None = None, *,
             c.fdr_q = qmap[id(c)]
 
     return CalibrationResult(real=real, surrogate_counts=surrogate_counts,
-                             B=B, alpha=alpha, q_target=q_target, null=null)
+                             B=B, alpha=alpha, q_target=q_target, null=null,
+                             n_observations=len(observations))
+
+
+# ---- comparing nulls ---------------------------------------------------------
+
+@dataclass
+class NullComparison:
+    """Calibration of one sample under several surrogate nulls, and their difference.
+
+    The informative output is the DIFFERENCE between nulls, not either null alone.
+    With the profile and rotation nulls the surviving sets nest, and split into:
+
+      * the *core*  -- patterns surviving under every null: the coupling (sequence)
+        claim, genuine coordination beyond each event type's own timing;
+      * the *shell* -- patterns surviving the rotation null but not the profile null:
+        co-occurrence driven by shared timing (two types that inhabit the same phase
+        of play) rather than by coordination.
+
+    The shell is a finding in its own right, not noise: it answers "which actions
+    occupy the same moment?" while the core answers "which actions are chained?".
+    Build one with compare_nulls().
+    """
+    nulls: list
+    method: str
+    q_target: float
+    results: dict            # null -> CalibrationResult
+    detected: dict           # null -> {signature: Calibrated} (detection is null-independent)
+    survives: dict           # null -> set(signature) surviving the correction
+    common: set              # signatures surviving under ALL nulls (the core)
+    unique: dict             # null -> set(signature) surviving under that null alone
+
+    def _q(self, null, sig):
+        c = self.detected[null].get(sig)
+        return None if c is None else c.fdr_q
+
+    def _N(self, sig):
+        for d in self.detected.values():
+            if sig in d:
+                return d[sig].N
+        return None
+
+    def layer(self, sig):
+        """Which layer a surviving pattern occupies: 'core', '<null>-only', or a join."""
+        surv = tuple(n for n in self.nulls if sig in self.survives[n])
+        if len(surv) == len(self.nulls):
+            return "core"
+        if len(surv) == 1:
+            return f"{surv[0]}-only"
+        return "+".join(surv) if surv else "none"
+
+    def rows(self):
+        """One row per pattern surviving under at least one null, most significant first.
+
+        Each row: signature, N, layer, and per-null (survives, q). Tidy for a table.
+        """
+        anysurv = set().union(*self.survives.values()) if self.survives else set()
+        sigs = sorted(anysurv, key=lambda s: min((self._q(n, s) or 1.0) for n in self.nulls))
+        return [{
+            "signature": s,
+            "N": self._N(s),
+            "layer": self.layer(s),
+            "survives": {n: (s in self.survives[n]) for n in self.nulls},
+            "q": {n: self._q(n, s) for n in self.nulls},
+        } for s in sigs]
+
+    def summary(self):
+        """Short text summary that leads with the difference between nulls."""
+        pr = set(self.nulls) >= {"profile", "rotation"}
+        lines = [f"{n:10s}: {len(self.survives[n])} survive ({self.method.upper()} q<={self.q_target})"
+                 for n in self.nulls]
+        lines.append(f"core (survives all{', the coupling claim' if pr else ''}): {len(self.common)}")
+        for n in self.nulls:
+            if self.unique[n]:
+                tag = " (shared-timing shell)" if (n == "rotation" and "profile" in self.nulls) else ""
+                lines.append(f"{n}-only{tag}: {len(self.unique[n])}")
+        return "\n".join(lines)
+
+    def __str__(self):
+        head = f"Null comparison [{', '.join(self.nulls)}]"
+        tab = [f"  {'pattern':<50s} {'N':>4s}  "
+               + "  ".join(f"{n[:8]:>9s}" for n in self.nulls) + "  layer"]
+        for r in self.rows():
+            cells = "  ".join(
+                ((f"{r['q'][n]:.3f}" if r['q'][n] is not None else "  -  ")
+                 + ("*" if r['survives'][n] else " ")).rjust(9)
+                for n in self.nulls)
+            tab.append(f"  {r['signature'][:50]:<50s} {r['N']:>4d}  {cells}  {r['layer']}")
+        return (head + "\n" + self.summary() + "\n\n" + "\n".join(tab)
+                + "\n  (* = survives the correction; q shown per null)")
+
+
+def compare_nulls(observations, config=None, *, nulls=("profile", "rotation"),
+                  B=200, alpha=0.005, q_target=0.05, method="fdr", seed=20260714):
+    """Calibrate one sample under several nulls and decompose the survivors.
+
+    This is the 'both' option: it runs calibrate() once per null and reports, for
+    every pattern, which nulls it survives under, so the DIFFERENCE between nulls is
+    explicit. With the default profile-vs-rotation pair the result splits into a
+    coupling core (survives both) and a shared-timing shell (rotation-only); the
+    shell is a positive finding, not noise (see NullComparison).
+
+    Parameters mirror calibrate(); `nulls` is the tuple of nulls to compare and
+    `method` selects "fdr" or "fwer" for deciding survival. Detection is identical
+    across nulls, so only the calibration is repeated.
+
+    Returns a NullComparison: print it for a table, or use .rows()/.common/.unique.
+    """
+    config = config or Config()
+    nulls = list(nulls)
+    results = {n: calibrate(observations, config, null=n, B=B, alpha=alpha,
+                            q_target=q_target, seed=seed) for n in nulls}
+    detected = {n: {c.pattern.signature(): c for c in results[n].real} for n in nulls}
+    survives = {n: {c.pattern.signature() for c in results[n].kept(method)} for n in nulls}
+    common = set.intersection(*survives.values()) if survives else set()
+    unique = {n: survives[n] - set().union(*[survives[m] for m in nulls if m != n])
+              for n in nulls}
+    return NullComparison(nulls=nulls, method=method, q_target=q_target,
+                          results=results, detected=detected, survives=survives,
+                          common=common, unique=unique)

tpattern-0.1.5/tpattern/viz.py

@@ -0,0 +1,274 @@
+"""
+Visual output for detected T-patterns — clean, publication-ready figures.
+
+The centrepiece is `pattern_dendrogram`: a T-pattern is a binary tree of
+critical-interval links, and this draws it as a proper dendrogram — event types
+as leaves, each internal join annotated with its critical interval [d1, d2] (the
+time window within which the right side follows the left). THEME draws this as a
+cramped detection tree; here it is a clean, labelled figure.
+"""
+
+from __future__ import annotations
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+from .pattern import Pattern
+
+
+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."""
+    if p.is_terminal:
+        x = len(leaves)
+        leaves.append(p.event)
+        pos[id(p)] = (x, 0)
+        return x, 0
+    lx, ld = _layout(p.left, leaves, pos)
+    rx, rd = _layout(p.right, leaves, pos)
+    x = (lx + rx) / 2.0
+    d = 1 + max(ld, rd)
+    pos[id(p)] = (x, d)
+    return x, d
+
+
+def _draw(p: Pattern, pos: dict, ax, ci_unit: str):
+    """Recursively draw dendrogram elbows from each internal node to its children."""
+    if p.is_terminal:
+        return
+    x, d = pos[id(p)]
+    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)
+        _draw(child, pos, ax, ci_unit)
+    # annotate the critical interval on the join
+    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")
+
+
+def pattern_dendrogram(pattern: Pattern, title: str | None = None,
+                       ci_unit: str = "", outfile: str | None = None, ax=None):
+    """Draw one T-pattern as a dendrogram. Returns the Axes.
+
+    Leaves (event types) are labelled along the bottom in temporal order; each
+    internal join shows its critical interval. `pattern.N` and significance can
+    be put in the title.
+    """
+    leaves: list = []
+    pos: dict = {}
+    _layout(pattern, leaves, pos)
+
+    own = ax is None
+    if own:
+        fig, ax = plt.subplots(figsize=(max(4, 1.1 * len(leaves)), 3.2))
+    _draw(pattern, pos, ax, ci_unit)
+
+    # leaf labels
+    for i, name in enumerate(leaves):
+        ax.plot([i], [0], "o", color="#2980b9", ms=6)
+        ax.annotate(name, (i, 0), textcoords="offset points", xytext=(0, -8),
+                    ha="right", va="top", rotation=35, fontsize=8)
+
+    ax.set_xlim(-0.7, len(leaves) - 0.3)
+    ax.set_ylim(-1.2, pattern.level + 0.6)
+    ax.set_yticks(range(pattern.level + 1))
+    ax.set_ylabel("level")
+    ax.set_xticks([])
+    for s in ("top", "right", "bottom"):
+        ax.spines[s].set_visible(False)
+    if title:
+        ax.set_title(title, fontsize=9, wrap=True)
+
+    if own and outfile:
+        plt.tight_layout(); plt.savefig(outfile, dpi=150); plt.close()
+    return ax
+
+
+def patterns_overview(patterns: list, outfile: str, max_rows: int = 8,
+                      ci_unit: str = "", by=lambda p: -p.N):
+    """A grid of the top pattern dendrograms (by `by`, default most frequent)."""
+    comps = sorted([p for p in patterns if p.level >= 1], key=by)[:max_rows]
+    n = len(comps)
+    if not n:
+        return
+    cols = 2
+    rows = (n + cols - 1) // cols
+    fig, axes = plt.subplots(rows, cols, figsize=(12, 3.0 * rows))
+    axes = axes.flatten() if n > 1 else [axes]
+    for ax, p in zip(axes, comps):
+        pattern_dendrogram(p, title=f"N={p.N}, level {p.level}", ci_unit=ci_unit, ax=ax)
+    for ax in axes[n:]:
+        ax.axis("off")
+    plt.tight_layout(); plt.savefig(outfile, dpi=150); plt.close()
+
+
+def support_profile(result, outfile: str, title: str | None = None,
+                    mark_thresholds=(0.10, 0.25), max_rows: int = 25,
+                    method: str = "fdr", color_by=None, highlight=None):
+    """Ranked bout-support profile of the patterns that survived calibration.
+
+    One bar per surviving pattern, ordered by the fraction of observations (bouts)
+    it spans. This reports prevalence instead of filtering on it: the reader sees
+    each pattern's spread directly and can apply whatever support threshold they
+    consider defensible.
+
+    `mark_thresholds` draws reference lines for candidate thresholds. Read them as
+    "everything below this line would be deleted", not as recommended values. A
+    knee in this profile separates common patterns from rare ones; it does NOT
+    separate real from chance, because calibration has already done that. Cutting
+    at a knee therefore removes rare patterns that are demonstrably not noise, and
+    on real data the knee ordering and the evidence ordering can disagree entirely.
+
+    Colouring the bars answers a question that generalises to any dataset: *does some
+    family of events cluster at one end of the prevalence range?* Two ways to ask it:
+
+    * ``highlight="LooseBall"`` (or a list of terms) colours every pattern whose
+      signature contains that text. No code needed, works with whatever labels your
+      own coding scheme uses.
+    * ``color_by=fn`` takes a callable mapping a signature to a group label, for
+      groupings a substring cannot express.
+
+    Leave both None for a single colour.
+
+    Returns the list of (signature, support) pairs actually plotted.
+    """
+    if color_by is None and highlight:
+        terms = [highlight] if isinstance(highlight, str) else list(highlight)
+
+        def color_by(sig, _terms=terms):
+            hit = next((t for t in _terms if t.lower() in sig.lower()), None)
+            return f"contains {hit}" if hit else "other patterns"
+
+    n_obs = getattr(result, "n_observations", 0)
+    items = []
+    for c in result.kept(method):
+        bouts = len({inst.obs for inst in c.pattern.instances})
+        items.append((c.pattern.signature(), bouts, bouts / n_obs if n_obs else 0.0))
+    items.sort(key=lambda x: -x[2])
+    shown = items[:max_rows]
+
+    n = len(shown)
+    # Long signatures are unreadable as rotated tick labels once there are more than
+    # a handful of bars, so rank-number them and let the caller print the key (the
+    # returned list) into the caption. Identity is recoverable, the shape stays clean.
+    number_bars = n > 6
+    fig, ax = plt.subplots(
+        figsize=((max(7.0, 0.42 * n + 2.2), 4.9) if number_bars
+                 else (max(6.0, 1.15 * n + 2.6), 5.2)), dpi=200)
+    if not shown:
+        ax.text(0.5, 0.5, "No pattern survived calibration,\nso there is no prevalence to report.",
+                ha="center", va="center", fontsize=10, color="#5b6270")
+        ax.axis("off")
+    else:
+        xs = range(n)
+        sup = [s for _, _, s in shown]
+        if color_by is None:
+            bar_colors = "#4a6fa5"
+        else:
+            palette = ["#4a6fa5", "#c07a3e", "#5b8c5a", "#8a6d9a"]
+            groups, seen = [], {}
+            for sig, _, _ in shown:
+                g = color_by(sig)
+                seen.setdefault(g, palette[len(seen) % len(palette)])
+                groups.append(g)
+            bar_colors = [seen[g] for g in groups]
+        bars = ax.bar(list(xs), sup, color=bar_colors, edgecolor="#2c4a72",
+                      width=0.68, zorder=3)
+        if color_by is not None:
+            from matplotlib.patches import Patch
+            ax.legend(handles=[Patch(facecolor=c, edgecolor="#2c4a72", label=g)
+                               for g, c in seen.items()],
+                      fontsize=7.4, frameon=False, loc="upper right")
+        ax.set_xticks(list(xs))
+        if number_bars:
+            ax.set_xticklabels([str(i + 1) for i in xs], fontsize=7.6)
+            ax.set_xlabel("pattern, ranked by prevalence (see caption for identities)",
+                          fontsize=8.4)
+        else:
+            ax.set_xticklabels([sig if len(sig) <= 34 else sig[:31] + "..."
+                                for sig, _, _ in shown],
+                               rotation=45, ha="right", fontsize=6.6)
+        ax.set_ylabel("bout support\n(fraction of observations the pattern appears in)",
+                      fontsize=8.4)
+        top = max(sup)
+        for i, (_, b, s) in enumerate(shown):
+            ax.text(i, s + top * 0.022, f"{s:.1%}", ha="center", va="bottom",
+                    fontsize=6.2, color="#1a1c22", zorder=4)
+        for thr in mark_thresholds or ():
+            lost = sum(1 for _, _, s in items if s < thr)
+            ax.axhline(thr, color="#b0303a", lw=1.1, ls="--", alpha=0.85, zorder=1)
+            ax.text(n - 0.4, thr, f"  {thr:.0%} would delete {lost} of {len(items)}",
+                    fontsize=6.8, color="#b0303a", va="bottom", ha="right")
+        ax.set_ylim(0, max(top * 1.30,
+                           (max(mark_thresholds) if mark_thresholds else 0) * 1.15))
+        ax.spines[["top", "right"]].set_visible(False)
+        ax.grid(axis="y", alpha=0.25, lw=0.6, zorder=0)
+        ax.yaxis.set_major_formatter(
+            matplotlib.ticker.FuncFormatter(lambda v, _: f"{v:.0%}"))
+    if title:
+        ax.set_title(title, fontsize=10.5, fontweight="bold")
+    if len(items) > max_rows:
+        fig.text(0.99, 0.005, f"showing {max_rows} of {len(items)} surviving patterns",
+                 ha="right", fontsize=6.8, color="#8a93a3")
+    fig.tight_layout()
+    fig.savefig(outfile)
+    plt.close(fig)
+    return [(sig, s) for sig, _, s in items]
+
+
+def null_comparison_plot(comparison, outfile, title=None, max_rows=25):
+    """Grid of which surrogate nulls each pattern survives, so the DIFFERENCE reads
+    at a glance. One row per pattern (surviving under at least one null), one column
+    per null; a filled cell means the pattern survives that null, annotated with its
+    q-value. Patterns are grouped core-first, then each null's unique (shell) set.
+
+    `comparison` is a NullComparison from compare_nulls(). Returns the rows plotted.
+    """
+    nulls = comparison.nulls
+    # order: core first, then each null's unique set, most significant within group
+    def _minq(sig):
+        return min((comparison._q(n, sig) or 1.0) for n in nulls)
+    ordered = ([s for s in sorted(comparison.common, key=_minq)]
+               + [s for n in nulls for s in sorted(comparison.unique[n], key=_minq)])
+    seen = set()
+    ordered = [s for s in ordered if not (s in seen or seen.add(s))][:max_rows]
+    if not ordered:
+        fig, ax = plt.subplots(figsize=(6, 2), dpi=200)
+        ax.text(0.5, 0.5, "No pattern survived under any null.", ha="center", va="center")
+        ax.axis("off"); fig.savefig(outfile); plt.close(fig); return []
+
+    GREEN, GREY, EDGE = "#2f7d4f", "#e4e7ec", "#333"
+    nrow, ncol = len(ordered), len(nulls)
+    fig, ax = plt.subplots(figsize=(3.0 + 1.5 * ncol, 1.1 + 0.42 * nrow), dpi=200)
+    for r, sig in enumerate(ordered):
+        y = nrow - 1 - r
+        layer = comparison.layer(sig)
+        for c, n in enumerate(nulls):
+            surv = sig in comparison.survives[n]
+            ax.add_patch(plt.Rectangle((c, y), 0.92, 0.92, facecolor=GREEN if surv else GREY,
+                                       edgecolor=EDGE, lw=0.6))
+            q = comparison._q(n, sig)
+            if q is not None:
+                ax.text(c + 0.46, y + 0.46, f"{q:.3f}", ha="center", va="center",
+                        fontsize=7.5, color="white" if surv else "#8a93a3",
+                        fontweight="bold" if surv else "normal")
+        ax.text(ncol + 0.15, y + 0.46, f"{sig}", ha="left", va="center", fontsize=7.4)
+        ax.text(-0.15, y + 0.46, layer, ha="right", va="center", fontsize=6.8,
+                color="#5b6270", style="italic")
+    ax.set_xlim(-2.4, ncol + 6.5); ax.set_ylim(-0.3, nrow + 0.2)
+    for c, n in enumerate(nulls):
+        ax.text(c + 0.46, nrow + 0.02, n, ha="center", va="bottom", fontsize=9, fontweight="bold")
+    ax.axis("off")
+    if title:
+        ax.set_title(title, fontsize=10.5, fontweight="bold", loc="left")
+    fig.text(0.5, 0.005, "filled = survives that null (q shown); core = survives all nulls, "
+             "shell = survives one null only", ha="center", fontsize=6.8, color="#8a93a3")
+    fig.tight_layout(rect=(0, 0.03, 1, 1))
+    fig.savefig(outfile)
+    plt.close(fig)
+    return ordered

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.2
+Version: 0.1.5
 Summary: Open, auditable temporal & sequential pattern analysis (T-patterns) for sport and behaviour
 Author-email: Andrew Callaway <acallaway@bournemouth.ac.uk>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/ajcallaway/TPattern
 Project-URL: Repository, https://github.com/ajcallaway/TPattern
 Project-URL: Archive (DOI), https://doi.org/10.5281/zenodo.21397543
@@ -15,7 +15,6 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering

{tpattern-0.1.2 → tpattern-0.1.5}/tpattern.egg-info/SOURCES.txt

@@ -5,7 +5,9 @@ tests/test_calibrated_pins.py
 tests/test_contrast.py
 tests/test_dedup.py
 tests/test_guided.py
+tests/test_null_compare.py
 tests/test_reproduction.py
+tests/test_support_reporting.py
 tests/test_synthetic.py
 tpattern/__init__.py
 tpattern/advisor.py

tpattern-0.1.2/tpattern/viz.py

@@ -1,107 +0,0 @@
-"""
-Visual output for detected T-patterns — clean, publication-ready figures.
-
-The centrepiece is `pattern_dendrogram`: a T-pattern is a binary tree of
-critical-interval links, and this draws it as a proper dendrogram — event types
-as leaves, each internal join annotated with its critical interval [d1, d2] (the
-time window within which the right side follows the left). THEME draws this as a
-cramped detection tree; here it is a clean, labelled figure.
-"""
-
-from __future__ import annotations
-
-import matplotlib
-matplotlib.use("Agg")
-import matplotlib.pyplot as plt
-
-from .pattern import Pattern
-
-
-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."""
-    if p.is_terminal:
-        x = len(leaves)
-        leaves.append(p.event)
-        pos[id(p)] = (x, 0)
-        return x, 0
-    lx, ld = _layout(p.left, leaves, pos)
-    rx, rd = _layout(p.right, leaves, pos)
-    x = (lx + rx) / 2.0
-    d = 1 + max(ld, rd)
-    pos[id(p)] = (x, d)
-    return x, d
-
-
-def _draw(p: Pattern, pos: dict, ax, ci_unit: str):
-    """Recursively draw dendrogram elbows from each internal node to its children."""
-    if p.is_terminal:
-        return
-    x, d = pos[id(p)]
-    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)
-        _draw(child, pos, ax, ci_unit)
-    # annotate the critical interval on the join
-    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")
-
-
-def pattern_dendrogram(pattern: Pattern, title: str | None = None,
-                       ci_unit: str = "", outfile: str | None = None, ax=None):
-    """Draw one T-pattern as a dendrogram. Returns the Axes.
-
-    Leaves (event types) are labelled along the bottom in temporal order; each
-    internal join shows its critical interval. `pattern.N` and significance can
-    be put in the title.
-    """
-    leaves: list = []
-    pos: dict = {}
-    _layout(pattern, leaves, pos)
-
-    own = ax is None
-    if own:
-        fig, ax = plt.subplots(figsize=(max(4, 1.1 * len(leaves)), 3.2))
-    _draw(pattern, pos, ax, ci_unit)
-
-    # leaf labels
-    for i, name in enumerate(leaves):
-        ax.plot([i], [0], "o", color="#2980b9", ms=6)
-        ax.annotate(name, (i, 0), textcoords="offset points", xytext=(0, -8),
-                    ha="right", va="top", rotation=35, fontsize=8)
-
-    ax.set_xlim(-0.7, len(leaves) - 0.3)
-    ax.set_ylim(-1.2, pattern.level + 0.6)
-    ax.set_yticks(range(pattern.level + 1))
-    ax.set_ylabel("level")
-    ax.set_xticks([])
-    for s in ("top", "right", "bottom"):
-        ax.spines[s].set_visible(False)
-    if title:
-        ax.set_title(title, fontsize=9, wrap=True)
-
-    if own and outfile:
-        plt.tight_layout(); plt.savefig(outfile, dpi=150); plt.close()
-    return ax
-
-
-def patterns_overview(patterns: list, outfile: str, max_rows: int = 8,
-                      ci_unit: str = "", by=lambda p: -p.N):
-    """A grid of the top pattern dendrograms (by `by`, default most frequent)."""
-    comps = sorted([p for p in patterns if p.level >= 1], key=by)[:max_rows]
-    n = len(comps)
-    if not n:
-        return
-    cols = 2
-    rows = (n + cols - 1) // cols
-    fig, axes = plt.subplots(rows, cols, figsize=(12, 3.0 * rows))
-    axes = axes.flatten() if n > 1 else [axes]
-    for ax, p in zip(axes, comps):
-        pattern_dendrogram(p, title=f"N={p.N}, level {p.level}", ci_unit=ci_unit, ax=ax)
-    for ax in axes[n:]:
-        ax.axis("off")
-    plt.tight_layout(); plt.savefig(outfile, dpi=150); plt.close()