tpattern 0.1.7__tar.gz → 0.1.9__tar.gz

{tpattern-0.1.7/tpattern.egg-info → tpattern-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.7
+Version: 0.1.9
 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.7 → tpattern-0.1.9}/pyproject.toml

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

tpattern-0.1.9/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.7 → tpattern-0.1.9}/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.7"   # defined before submodule imports (methods.py reads it)
+__version__ = "0.1.9"   # 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.7 → tpattern-0.1.9}/tpattern/io.py

@@ -116,8 +116,8 @@ def read_sample(folder: str | Path, pattern: str = "*.txt") -> list[Observation]
 
 def read_table(path: str | Path, *, observation: str = "observation",
                event: str = "event", start: str = "start",
-               end: str | None = None, obs_start: str | None = None,
-               obs_end: str | None = None, build_event_from: list[str] | None = None,
+               end: str | None = "end", obs_start: str | None = "obs_start",
+               obs_end: str | None = "obs_end", build_event_from: list[str] | None = None,
                time_unit: str = "s", sep: str = ",") -> list[Observation]:
     """Read the canonical flat event table (see SCHEMA.md) into a sample.
 
@@ -135,11 +135,14 @@ def read_table(path: str | Path, *, observation: str = "observation",
         taken from the min/max event `start`.
     obs_start, obs_end : str, optional
         Columns giving the *observation window* (constant within an observation).
-        Supply these when the unit has real bounds that extend beyond its first and
-        last event — a possession, rally or bout usually does. The window length
-        T = obs_end - obs_start is the denominator of the NX/T baseline, so deriving
-        it from the events instead will shift every baseline probability. If absent,
-        the window falls back to the first/last event time.
+        These default to the conventional column names ("obs_start"/"obs_end"), so a
+        table that includes them is read correctly with **no arguments**; they are
+        ignored silently if the columns are absent. Supply a window when the unit has
+        real bounds that extend beyond its first and last event — a possession, rally
+        or bout usually does. The window length T = obs_end - obs_start is the
+        denominator of the NX/T baseline, so deriving it from the events instead will
+        shift every baseline probability. If absent, the window falls back to the
+        first/last event time.
     build_event_from : list[str], optional
         If given, the event code is built by joining these columns with '_'
         (for coders who keep the code split across descriptor columns) instead of
@@ -212,3 +215,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.7 → tpattern-0.1.9/tpattern.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tpattern
-Version: 0.1.7
+Version: 0.1.9
 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.7 → tpattern-0.1.9}/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