tpattern 0.1.6__tar.gz → 0.1.8__tar.gz

{tpattern-0.1.6/tpattern.egg-info → tpattern-0.1.8}/PKG-INFO

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

{tpattern-0.1.6 → tpattern-0.1.8}/pyproject.toml

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

tpattern-0.1.8/tests/test_sofcoder.py

@@ -0,0 +1,67 @@
+"""read_sofcoder: ingest a SOF-CODER / THEME DATANAME,T,Events file."""
+from tpattern import read_sofcoder, Engine, Config
+
+SAMPLE = (
+    "DATANAME\tT\tEvents\n"
+    "FCB-BETIS_FIRST\t1\t:\n"
+    "FCB-BETIS_FIRST\t375\tCE,UD,IR,RA\n"
+    "FCB-BETIS_FIRST\t650\tCE,UD,FT,RA\n"
+    "FCB-BETIS_FIRST\t3775\tCE,C,MM\n"
+    "FCB-BETIS_FIRST\t4000\t&\n"
+    "RM-VALENCIA\t1\t:\n"
+    "RM-VALENCIA\t500\tIZ,O,AR\n"
+)
+
+
+def _write(tmp_path, text, name="sof.csv"):
+    p = tmp_path / name
+    p.write_text(text)
+    return str(p)
+
+
+def test_sessions_and_explode(tmp_path):
+    obs = read_sofcoder(_write(tmp_path, SAMPLE))
+    assert [o.name for o in obs] == ["FCB-BETIS_FIRST", "RM-VALENCIA"]
+    fcb = obs[0]
+    # 3 event-rows exploded: 4 + 4 + 3 codes = 11 events (markers excluded)
+    assert len(fcb.events) == 11
+    # CE,UD,IR,RA all land at t=375 as co-timed events
+    assert sorted(c for t, c in fcb.events if t == 375) == ["CE", "IR", "RA", "UD"]
+    # no marker leaked into the events
+    assert all(c not in (":", "&") for _, c in fcb.events)
+
+
+def test_window_from_markers(tmp_path):
+    # the : and & markers define the observation window (the NX/T denominator)
+    obs = read_sofcoder(_write(tmp_path, SAMPLE))
+    fcb = obs[0]
+    assert (fcb.start, fcb.end) == (1, 4000)
+    # a session without an & marker falls back to the last event
+    rm = obs[1]
+    assert rm.start == 1 and rm.end == 500
+
+
+def test_whitespace_delimiter(tmp_path):
+    text = "DATANAME T Events\nS1 1 :\nS1 100 A,B\nS1 200 A,C\nS1 300 &\n"
+    obs = read_sofcoder(_write(tmp_path, text, "ws.csv"))
+    assert obs[0].events == [(100, "A"), (100, "B"), (200, "A"), (200, "C")]
+    assert (obs[0].start, obs[0].end) == (1, 300)
+
+
+def test_frames_per_second_scaling(tmp_path):
+    # frames -> ms: at 25 fps, frame 25 == 1000 ms
+    text = "DATANAME T Events\nS1 25 A,B\nS1 50 A\n"
+    obs = read_sofcoder(_write(tmp_path, text, "fps.csv"), frames_per_second=25)
+    assert obs[0].events[0][0] == 1000
+
+
+def test_flows_into_detection(tmp_path):
+    obs = read_sofcoder(_write(tmp_path, SAMPLE))
+    pats = Engine(obs, Config(min_lag=0)).detect()
+    assert isinstance(pats, list)  # runs without error on SOF-CODER-sourced data
+
+
+def test_positional_no_header(tmp_path):
+    text = "S1 10 A,B\nS1 20 C\n"
+    obs = read_sofcoder(_write(tmp_path, text, "noheader.csv"))
+    assert obs[0].name == "S1" and len(obs[0].events) == 3

{tpattern-0.1.6 → tpattern-0.1.8}/tpattern/__init__.py

@@ -6,9 +6,9 @@ behavior: T-patterns and their detection. Behavior Research Methods,
 Instruments, & Computers, 32(1), 93-110.
 """
 
-__version__ = "0.1.6"   # defined before submodule imports (methods.py reads it)
+__version__ = "0.1.8"   # defined before submodule imports (methods.py reads it)
 
-from .io import Observation, read_observation, read_sample, read_table
+from .io import Observation, read_observation, read_sample, read_table, read_sofcoder
 from .pattern import Instance, Pattern
 from .ci import find_critical_interval, CIResult
 from .detect import Config, Engine
@@ -23,7 +23,7 @@ from .guided import run_analysis, launch
 from .contrast import group_contrast, contrast_items
 
 __all__ = [
-    "Observation", "read_observation", "read_sample", "read_table",
+    "Observation", "read_observation", "read_sample", "read_table", "read_sofcoder",
     "Instance", "Pattern",
     "find_critical_interval", "CIResult",
     "Config", "Engine",

{tpattern-0.1.6 → tpattern-0.1.8}/tpattern/advisor.py

@@ -50,12 +50,55 @@ class Recommendation:
     notes: list[str] = field(default_factory=list)
 
     def __str__(self) -> str:
-        lines = [f"Dataset: {self.n_obs} observations, {self.n_events} events\n"]
+        """Readable plain-text view: each setting, its recommended value, then the
+        wrapped reason. Kept ANSI/markup-free so it can be pasted verbatim."""
+        import textwrap
+        w = 76
+
+        def wrap(text, first, rest):
+            return textwrap.fill(text, width=w, initial_indent=first,
+                                 subsequent_indent=rest)
+
+        out = ["=" * w,
+               f"RECOMMENDED SETTINGS   ({self.n_obs:,} observations, "
+               f"{self.n_events:,} events)",
+               "=" * w]
         for c in self.choices:
-            lines.append(f"[{c.option}]  ->  {c.recommended}\n    {c.rationale}")
+            out += ["", f"  {c.option}  ->  {c.recommended}",
+                    wrap(c.rationale, "     ", "     ")]
         for n in self.notes:
-            lines.append(f"[note]  {n}")
-        return "\n".join(lines)
+            out += ["", wrap(n, "  * ", "    ")]
+        return "\n".join(out)
+
+    def _repr_html_(self) -> str:
+        """Rich rendering in notebooks (Colab/Jupyter): the recommended value in
+        bold, the setting name and explanation in normal weight. Shown when you
+        display the object (a bare `rec` or `display(rec)`); `print(rec)` still
+        gives the plain-text view above."""
+        import html
+
+        def esc(s):
+            return html.escape(str(s))
+
+        rows = "".join(
+            '<div style="margin:0 0 11px 0;">'
+            f'<div><span style="color:#6b7280;">{esc(c.option)}:</span> '
+            f'<strong style="color:#111;">{esc(c.recommended)}</strong></div>'
+            f'<div style="color:#4b5563;margin-top:2px;">{esc(c.rationale)}</div>'
+            '</div>'
+            for c in self.choices)
+        notes = ""
+        if self.notes:
+            lis = "".join(f'<li style="color:#4b5563;margin:2px 0;">{esc(n)}</li>'
+                          for n in self.notes)
+            notes = f'<ul style="margin:6px 0 0 0;padding-left:18px;">{lis}</ul>'
+        return (
+            '<div style="font-family:system-ui,-apple-system,Segoe UI,sans-serif;'
+            'font-size:13px;line-height:1.5;max-width:780px;">'
+            '<div style="font-weight:600;font-size:14px;margin-bottom:8px;'
+            'padding-bottom:5px;border-bottom:1px solid #e5e7eb;">'
+            f'Recommended settings &nbsp;&middot;&nbsp; {self.n_obs:,} observations, '
+            f'{self.n_events:,} events</div>{rows}{notes}</div>')
 
     def methods_text(self) -> str:
         """A ready-to-adapt Methods paragraph, grounded in the measured values."""

{tpattern-0.1.6 → tpattern-0.1.8}/tpattern/io.py

@@ -212,3 +212,89 @@ def read_table(path: str | Path, *, observation: str = "observation",
             o_end = max(ends_by_obs[obs_id]) if ends_by_obs.get(obs_id) else evs[-1][0]
         sample.append(Observation(name=obs_id, start=o_start, end=o_end, events=evs))
     return sample
+
+
+def read_sofcoder(path: str | Path, *, dataname: str = "DATANAME",
+                  t: str = "T", events: str = "Events", sep: str | None = None,
+                  code_sep: str = ",", frames_per_second: float | None = None,
+                  start_marker: str = ":", end_marker: str = "&") -> list[Observation]:
+    """Read a SOF-CODER / THEME data file (DATANAME, T, Events) into a sample.
+
+    SOF-CODER (Jonsson et al., 2006) exports one row per time frame, each row
+    carrying several comma-separated category codes active at that frame (its
+    multi-criteria "field format"). This reader explodes each row so every code
+    becomes one event at time ``T``; codes that share a frame are co-timed, and
+    ``min_lag``/``collapse_duplicates`` then decide how co-occurrence is treated.
+    Each ``DATANAME`` becomes one :class:`Observation`. Rows whose Events field is
+    the start (``:``) or end (``&``) marker set the observation window
+    ``[start, end]`` (``T = end - start`` is the NX/T baseline denominator); if the
+    markers are absent the window falls back to the first/last event.
+
+    The outer column delimiter is auto-detected (tab if present, else any
+    whitespace) unless ``sep`` is given; ``code_sep`` splits the Events field
+    (default ``','``). ``T`` is kept in the file's native frame unit unless
+    ``frames_per_second`` is supplied, in which case frames are converted to
+    milliseconds. A header row naming the columns is used if present, else the
+    columns are taken positionally as (DATANAME, T, Events).
+
+    This is the on-ramp for data collected in the SOF-CODER/THEME ecosystem; for
+    a coder that already exports one row per single event, use :func:`read_table`.
+    """
+    path = Path(path)
+    scale = (1000.0 / frames_per_second) if frames_per_second else 1.0
+
+    def split_row(line: str) -> list[str]:
+        if sep is not None:
+            parts = line.split(sep)
+        elif "\t" in line:
+            parts = line.split("\t")
+        else:
+            parts = line.split(None, 2)   # DATANAME, T, Events (Events holds no spaces)
+        return [p.strip() for p in parts]
+
+    with open(path, newline="") as fh:
+        lines = [ln.strip() for ln in fh if ln.strip()]
+    if not lines:
+        return []
+
+    header = [h.lower() for h in split_row(lines[0])]
+    if dataname.lower() in header and events.lower() in header:
+        di, ti, ei = (header.index(dataname.lower()), header.index(t.lower()),
+                      header.index(events.lower()))
+        body = lines[1:]
+    else:
+        di, ti, ei, body = 0, 1, 2, lines   # positional fallback
+
+    rows_by_obs: dict[str, list] = defaultdict(list)
+    starts: dict[str, int] = {}
+    ends: dict[str, int] = {}
+    for line in body:
+        parts = split_row(line)
+        if len(parts) <= max(di, ti, ei):
+            continue
+        obs_id = parts[di]
+        if not obs_id:
+            continue
+        try:
+            tv = int(round(float(parts[ti]) * scale))
+        except (ValueError, TypeError):
+            continue
+        raw = parts[ei]
+        if raw == start_marker:
+            starts.setdefault(obs_id, tv)
+            continue
+        if raw == end_marker:
+            ends[obs_id] = tv
+            continue
+        for code in raw.split(code_sep):
+            code = code.strip()
+            if code and code not in (start_marker, end_marker):
+                rows_by_obs[obs_id].append((tv, code))
+
+    sample: list[Observation] = []
+    for obs_id, evs in rows_by_obs.items():
+        evs.sort(key=lambda e: e[0])
+        o_start = starts.get(obs_id, evs[0][0])
+        o_end = ends.get(obs_id, evs[-1][0])
+        sample.append(Observation(name=obs_id, start=o_start, end=o_end, events=evs))
+    return sample

{tpattern-0.1.6 → tpattern-0.1.8/tpattern.egg-info}/PKG-INFO

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

{tpattern-0.1.6 → tpattern-0.1.8}/tpattern.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ tests/test_guided.py
 tests/test_null_compare.py
 tests/test_report_dendrogram.py
 tests/test_reproduction.py
+tests/test_sofcoder.py
 tests/test_support_reporting.py
 tests/test_synthetic.py
 tpattern/__init__.py