sfm-analysis 0.1.0__py3-none-any.whl

sfm_analysis/__init__.py

@@ -0,0 +1,18 @@
+"""sfm_analysis — cross-platform analysis and reporting for VFM/SFM feeder logs.
+
+Reads the session CSVs written by the VFM base station (``packages/dev_gui`` in
+the parent repo, https://github.com/Neurotech-Hub/VFM) and turns them into
+printable HTML behavior reports, with no dependency on the Raspberry Pi
+base-station GUI or any hardware library. Install with ``pip install
+sfm-analysis`` on Windows, macOS, or Linux and run ``sfm-report`` — see
+README.md for the full CLI and the Python analysis API.
+
+This package is stdlib-only by design: no jinja2, no pandas, no matplotlib.
+Reports are self-contained HTML with inline SVG, printable via Ctrl+P.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

sfm_analysis/analysis/__init__.py

@@ -0,0 +1,50 @@
+"""analysis — the curated Python API for custom session analysis.
+
+Everything below is stable, documented, and safe to build on. It sits on
+top of ``sfm_analysis.report`` (loading, run-splitting, metrics) without
+requiring you to know that package's internals — see this package's
+functions' docstrings for worked examples, and
+``packages/sfm-analysis/README.md``'s "five things to know" section for
+the pitfalls a session log has that aren't obvious from the CSV alone.
+
+    from sfm_analysis.analysis import load_session
+
+    s = load_session("EXP-Test-02")
+    cycles = s.cycles_table()          # list[dict], one row per dispense cycle
+    bouts = s.bouts_table()            # presence / dome / fault intervals
+
+Everything here returns plain ``list[dict]`` / dataclasses / floats — no
+pandas dependency. Call ``to_dataframe(rows)`` if you have pandas
+installed and want one.
+"""
+
+from __future__ import annotations
+
+from . import intervals
+from .intervals import around, count_in, merge, overlap, rate_in, subtract
+from .session import AmbiguousSessionError, Session, SessionNotFoundError, load_session
+from .tables import bouts_table, cycles_table, events_table, to_dataframe, trials_table
+from ..report.timezones import local_date, time_of_day, wall_clock, zeitgeber_time
+
+__all__ = [
+    "load_session",
+    "Session",
+    "SessionNotFoundError",
+    "AmbiguousSessionError",
+    "cycles_table",
+    "bouts_table",
+    "events_table",
+    "trials_table",
+    "to_dataframe",
+    "intervals",
+    "overlap",
+    "subtract",
+    "merge",
+    "around",
+    "count_in",
+    "rate_in",
+    "time_of_day",
+    "local_date",
+    "zeitgeber_time",
+    "wall_clock",
+]

sfm_analysis/analysis/intervals.py

@@ -0,0 +1,149 @@
+"""intervals.py — generic interval algebra for behavioral analysis.
+
+Every "was X happening while Y" question a session log gets asked reduces
+to one of these six functions. An interval is a plain ``(t0, t1)`` tuple
+of run-relative seconds (the same ``t`` every RunData row and Bout/
+FaultInterval/Cycle already carries) with ``t0 <= t1``; a set of intervals
+is any ``Sequence`` of them, not necessarily sorted or merged.
+
+Deliberately *not* method calls on Bout/FaultInterval: those objects can
+be ``censored`` (``t1=None``, still open when the run ended), and this
+module refuses to guess what a censored interval's end time should be —
+see ``as_intervals`` below. Resolve that explicitly (usually to
+``run.duration_s``) before handing data here, the same way
+``metrics.bouts()`` already does internally.
+
+Example::
+
+    from sfm_analysis.analysis import intervals as iv
+
+    presence, _ = m.presence                    # List[Bout]
+    dome, _ = m.dome                             # List[Bout]
+    presence_iv = iv.as_intervals(presence, run_end=run.duration_s)
+    dome_iv = iv.as_intervals(dome, run_end=run.duration_s)
+
+    # Dome opened while the mouse was present:
+    len(iv.overlap(dome_iv, presence_iv))
+
+    # Takes within 30s after a fault started:
+    fault_iv = iv.as_intervals(m.faults, run_end=run.duration_s)
+    take_times = [r.t for r in run.by_event("Pellet Taken")]
+    iv.count_in(take_times, iv.around([f[0] for f in fault_iv], (0, 30)))
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, Sequence, Tuple
+
+Interval = Tuple[float, float]
+
+
+def as_intervals(objs: Sequence[Any], *, run_end: Optional[float] = None) -> List[Interval]:
+    """
+    Convert a sequence of Bout/FaultInterval-like objects (anything with
+    ``.t0`` and ``.t1`` attributes) into plain ``(t0, t1)`` tuples.
+
+    Raises ValueError on a censored object (``t1 is None``) unless
+    ``run_end`` is given, in which case its ``t1`` becomes ``run_end`` —
+    matching how the report's own ``metrics.bouts()`` resolves an
+    unclosed bout. This is a required, explicit choice: silently treating
+    a censored interval as zero-length or infinite would both be wrong,
+    and differently wrong depending on the question being asked.
+    """
+    out: List[Interval] = []
+    for obj in objs:
+        t0 = float(obj.t0)
+        t1 = obj.t1
+        if t1 is None:
+            if run_end is None:
+                raise ValueError(
+                    "censored interval (t1=None) with no run_end given — "
+                    "pass run_end=run.duration_s to resolve it, or filter "
+                    "out censored objects first if that's what you want"
+                )
+            t1 = run_end
+        out.append((t0, float(t1)))
+    return out
+
+
+def _clip(a: Interval, b: Interval) -> Optional[Interval]:
+    lo = max(a[0], b[0])
+    hi = min(a[1], b[1])
+    return (lo, hi) if lo < hi else None
+
+
+def overlap(a: Sequence[Interval], b: Sequence[Interval]) -> List[Interval]:
+    """Every sub-interval present in both ``a`` and ``b``."""
+    out: List[Interval] = []
+    for ia in a:
+        for ib in b:
+            clipped = _clip(ia, ib)
+            if clipped is not None:
+                out.append(clipped)
+    return merge(out)
+
+
+def subtract(a: Sequence[Interval], b: Sequence[Interval]) -> List[Interval]:
+    """The parts of ``a`` not covered by any interval in ``b``."""
+    b_merged = merge(b)
+    out: List[Interval] = []
+    for t0, t1 in a:
+        cursor = t0
+        for b0, b1 in b_merged:
+            if b1 <= cursor or b0 >= t1:
+                continue
+            if b0 > cursor:
+                out.append((cursor, min(b0, t1)))
+            cursor = max(cursor, b1)
+            if cursor >= t1:
+                break
+        if cursor < t1:
+            out.append((cursor, t1))
+    return out
+
+
+def merge(intervals: Sequence[Interval], *, gap: float = 0.0) -> List[Interval]:
+    """
+    Merge overlapping (or, with ``gap > 0``, near-adjacent) intervals into
+    the smallest equivalent set, sorted by start time.
+    """
+    if not intervals:
+        return []
+    ordered = sorted(intervals, key=lambda iv: iv[0])
+    out: List[Interval] = [ordered[0]]
+    for t0, t1 in ordered[1:]:
+        last0, last1 = out[-1]
+        if t0 <= last1 + gap:
+            out[-1] = (last0, max(last1, t1))
+        else:
+            out.append((t0, t1))
+    return out
+
+
+def around(events: Sequence[float], window: Interval) -> List[Interval]:
+    """
+    A peri-event interval ``(t + window[0], t + window[1])`` around each
+    event timestamp in ``events``. ``window`` is an offset pair, e.g.
+    ``(-5, 30)`` for "5s before to 30s after".
+    """
+    lo, hi = window
+    return [(t + lo, t + hi) for t in events]
+
+
+def count_in(events: Sequence[float], intervals: Sequence[Interval]) -> int:
+    """How many of ``events`` fall inside any of ``intervals`` (inclusive)."""
+    merged = merge(intervals)
+    return sum(1 for t in events if any(t0 <= t <= t1 for t0, t1 in merged))
+
+
+def rate_in(events: Sequence[float], intervals: Sequence[Interval]) -> Optional[float]:
+    """Events per second, over the total (merged) duration of ``intervals``.
+
+    None if the total duration is zero, rather than raising or returning
+    an infinite rate.
+    """
+    merged = merge(intervals)
+    total = sum(t1 - t0 for t0, t1 in merged)
+    if total <= 0:
+        return None
+    return count_in(events, merged) / total

sfm_analysis/analysis/session.py

@@ -0,0 +1,127 @@
+"""analysis/session.py — the one-line entry point: name/glob/path -> Session.
+
+``load_session`` is what makes analysis start with one import and one call
+instead of five imports across four modules (loader, session, metrics,
+logs). See the module docstring of ``sfm_analysis.analysis`` for a worked
+example.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, List, Optional
+
+from ..report import load_runs
+from ..report.metrics import RunMetrics, compute_run_metrics
+from ..storage import default_log_dir
+from ..targeting import resolve_targets
+
+if TYPE_CHECKING:
+    from ..report.session import RunData
+
+
+class SessionNotFoundError(LookupError):
+    """Raised by load_session when a target matches no session CSV."""
+
+
+class AmbiguousSessionError(LookupError):
+    """Raised by load_session when a target matches more than one session
+    CSV — pass an exact session name or an explicit path to disambiguate,
+    or use sfm_analysis.report.loader.discover_sessions directly if you
+    actually want every match."""
+
+
+@dataclass
+class Session:
+    """One session CSV, loaded and split into runs, with metrics for every
+    run precomputed once. Returned by ``load_session`` — see that
+    function's docstring for how to get one.
+
+    A CSV can hold more than one *run* (reopening a session name appends
+    to the file and starts a new run_id — see ``.runs``); most of what
+    you want is on the run that actually happened, not an aborted
+    restart, which is what ``.run()`` picks by default.
+    """
+
+    name: str
+    path: Path
+    runs: "List[RunData]" = field(default_factory=list)
+    metrics: List[RunMetrics] = field(default_factory=list)
+
+    def run(self, run_id: Optional[int] = None) -> "RunData":
+        """
+        The run to use when exactly one is needed.
+
+        With ``run_id`` given, returns that run or raises LookupError.
+        Otherwise: the only run if there's just one, else the run with
+        the most rows -- a session file with a 9-row aborted restart
+        followed by the real 500-row session should hand you the real
+        one by default, not silently the first (usually abortive) run_id.
+        Use ``.runs`` directly if you want every run, or pass
+        ``run_id=...`` to every table method to be explicit.
+        """
+        if run_id is not None:
+            for r in self.runs:
+                if r.run_id == run_id:
+                    return r
+            available = sorted(r.run_id for r in self.runs)
+            raise LookupError(f"No run_id={run_id} in {self.name!r} (available: {available})")
+        if len(self.runs) == 1:
+            return self.runs[0]
+        return max(self.runs, key=lambda r: len(r.rows))
+
+    def metrics_for(self, run_id: Optional[int] = None) -> RunMetrics:
+        """RunMetrics for the same run ``.run(run_id)`` would return."""
+        target = self.run(run_id)
+        idx = self.runs.index(target)
+        return self.metrics[idx]
+
+    def cycles_table(self, run_id: Optional[int] = None) -> List[dict]:
+        from .tables import cycles_table
+        return cycles_table(self, run_id=run_id)
+
+    def bouts_table(self, run_id: Optional[int] = None) -> List[dict]:
+        from .tables import bouts_table
+        return bouts_table(self, run_id=run_id)
+
+    def events_table(self, run_id: Optional[int] = None, **filters) -> List[dict]:
+        from .tables import events_table
+        return events_table(self, run_id=run_id, **filters)
+
+    def trials_table(self, run_id: Optional[int] = None) -> List[dict]:
+        from .tables import trials_table
+        return trials_table(self, run_id=run_id)
+
+
+def load_session(target: str, *, log_dir: Optional[Path] = None) -> Session:
+    """
+    Resolve ``target`` — a session name, shell glob, or explicit path to a
+    ``.csv`` — against ``log_dir`` (default: the same auto-detection
+    ``sfm-report`` uses: ``$SFM_LOG_DIR``, else an external drive's
+    ``sfm_logs/``, else ``~/sfm_logs``) and load it.
+
+    Raises ``SessionNotFoundError`` if nothing matches, or
+    ``AmbiguousSessionError`` if a glob matches more than one session —
+    pass an exact name or path instead.
+
+    Example::
+
+        from sfm_analysis.analysis import load_session
+
+        s = load_session("EXP-Test-02")
+        s = load_session("cohortA_M014_d3.csv", log_dir="/data/sfm_logs")
+    """
+    resolved_log_dir = Path(log_dir) if log_dir is not None else Path(default_log_dir())
+    matches = resolve_targets([target], resolved_log_dir)
+    if not matches:
+        raise SessionNotFoundError(f"No session matched {target!r} in {resolved_log_dir}")
+    if len(matches) > 1:
+        names = ", ".join(p.stem for p in matches)
+        raise AmbiguousSessionError(
+            f"{target!r} matched {len(matches)} sessions in {resolved_log_dir}: {names}"
+        )
+    path = matches[0]
+    runs = load_runs(path)
+    metrics = [compute_run_metrics(r) for r in runs]
+    return Session(name=path.stem, path=path, runs=runs, metrics=metrics)

sfm_analysis/analysis/tables.py

@@ -0,0 +1,203 @@
+"""tables.py — tidy list[dict] tables for custom analysis.
+
+Every function here flattens one kind of already-computed data (cycles,
+bouts, raw events, trial markers) into a list of plain dicts, one dict
+per row, every row carrying the same keys. Feed the result straight to
+``pd.DataFrame(...)`` if you have pandas, or iterate it directly.
+
+Deliberately not a query DSL: filter/group/join in pandas (or plain
+Python) once you have the table, not through a bespoke API here. See
+``to_dataframe()`` for the pandas handoff.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence, Tuple
+
+if TYPE_CHECKING:
+    from ..report.session import RunData
+    from .session import Session
+
+
+def _runs_and_metrics(session: "Session", run_id: Optional[int]) -> List[Tuple["RunData", Any]]:
+    if run_id is not None:
+        return [(session.run(run_id), session.metrics_for(run_id))]
+    return list(zip(session.runs, session.metrics))
+
+
+def cycles_table(session: "Session", run_id: Optional[int] = None) -> List[Dict[str, Any]]:
+    """
+    One row per reconstructed dispense cycle (``metrics.Cycle``), across
+    every run in ``session`` unless ``run_id`` is given.
+
+    Example::
+
+        rows = s.cycles_table()
+        latencies = [r["retrieval_latency"] for r in rows if r["retrieval_latency"] is not None]
+    """
+    out: List[Dict[str, Any]] = []
+    for run, m in _runs_and_metrics(session, run_id):
+        for c in m.cycles:
+            out.append({
+                "session": session.name,
+                "run_id": run.run_id,
+                "node": c.node,
+                "trial": c.trial,
+                "index": c.index,
+                "fed": c.fed,
+                "cmd_t": c.cmd_t,
+                "lowering_t": c.lowering_t,
+                "loading_t": c.loading_t,
+                "on_plate_t": c.on_plate_t,
+                "raising_t": c.raising_t,
+                "seeking_t": c.seeking_t,
+                "dwelling_t": c.dwelling_t,
+                "ready_t": c.ready_t,
+                "first_presence_t": c.first_presence_t,
+                "first_dome_t": c.first_dome_t,
+                "taken_t": c.taken_t,
+                "end_t": c.end_t,
+                "censored": c.censored,
+                "cycle_duration": c.cycle_duration,
+                "approach_latency": c.approach_latency,
+                "dome_latency": c.dome_latency,
+                "handling_time": c.handling_time,
+                "retrieval_latency": c.retrieval_latency,
+                "approached_without_dome": c.approached_without_dome,
+                "dome_without_take": c.dome_without_take,
+            })
+    return out
+
+
+def bouts_table(session: "Session", run_id: Optional[int] = None) -> List[Dict[str, Any]]:
+    """
+    One row per presence bout, dome-open bout, and fault interval,
+    unified under a ``kind`` column (``"presence"`` | ``"dome"`` |
+    ``"fault"``). A ``censored`` row was still open when the run ended —
+    its ``t1``/``dur`` are ``None``, not zero; filter deliberately (see
+    the "five things to know" section of the README) rather than letting
+    a censored bout silently become a zero-duration one in an average.
+    """
+    out: List[Dict[str, Any]] = []
+    for run, m in _runs_and_metrics(session, run_id):
+        presence_bouts, _ = m.presence
+        dome_bouts, _ = m.dome
+        for kind, bouts in (("presence", presence_bouts), ("dome", dome_bouts)):
+            for b in bouts:
+                out.append({
+                    "session": session.name,
+                    "run_id": run.run_id,
+                    "kind": kind,
+                    "node": b.node,
+                    "t0": b.t0,
+                    "t1": b.t1,
+                    "dur": b.dur,
+                    "censored": b.censored,
+                    "code": None,
+                    "inferred_close": None,
+                })
+        for f in m.faults:
+            out.append({
+                "session": session.name,
+                "run_id": run.run_id,
+                "kind": "fault",
+                "node": f.node,
+                "t0": f.t0,
+                "t1": f.t1,
+                "dur": f.dur,
+                "censored": f.censored,
+                "code": f.code.name,
+                "inferred_close": f.inferred_close,
+            })
+    return out
+
+
+def events_table(
+    session: "Session",
+    run_id: Optional[int] = None,
+    *,
+    source: Optional[str] = None,
+    frame_type: Optional[str] = None,
+    event_name: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """
+    One row per raw log row (``LogRow``), optionally filtered by
+    ``source`` (``"CAN"``/``"EXP"``/``"BNC"``/``"SYS"``), ``frame_type``,
+    or ``event_name``.
+
+    This is the escape hatch: every row sfm_analysis parses is here, with
+    its ``fields_json`` already decoded into a ``fields`` dict. Prefer
+    ``cycles_table()`` / ``bouts_table()`` for anything they already
+    cover — this is for the question those don't answer.
+
+    Watch the "Dome Opened" trap if you filter on it directly:
+    ``event_name="Dome Opened"`` matches two different wire events (a
+    milestone and a renamed edge — see the README) and double-counts
+    every physical opening. ``bouts_table(kind="dome")`` already does
+    the dedup; use that instead of filtering this table by name.
+    """
+    out: List[Dict[str, Any]] = []
+    for run, _m in _runs_and_metrics(session, run_id):
+        for row in run.rows:
+            if source is not None and row.source != source:
+                continue
+            if frame_type is not None and row.frame_type != frame_type:
+                continue
+            if event_name is not None and row.event_name != event_name:
+                continue
+            out.append({
+                "session": session.name,
+                "run_id": run.run_id,
+                "t": row.t,
+                "iso": row.iso,
+                "node_id": row.node_id,
+                "trial": row.trial,
+                "source": row.source,
+                "direction": row.direction,
+                "frame_type": row.frame_type,
+                "event_name": row.event_name,
+                "fields": row.fields,
+                "details": row.details,
+                "post_session": row.post_session,
+            })
+    return out
+
+
+def trials_table(session: "Session", run_id: Optional[int] = None) -> List[Dict[str, Any]]:
+    """
+    One row per generic ``trial`` marker row (EXPERIMENT source,
+    ``event_name="trial"``) — the trial-boundary event every experiment
+    template logs, regardless of what happens inside the trial. For
+    template-specific trial structure (choice, reward, block), see the
+    corresponding ``sfm_analysis.report.analyses`` module instead (e.g.
+    ``analyses.bandit.build_trials`` for ``two_armed_bandit``).
+    """
+    out: List[Dict[str, Any]] = []
+    for run, _m in _runs_and_metrics(session, run_id):
+        for row in run.exp("trial"):
+            out.append({
+                "session": session.name,
+                "run_id": run.run_id,
+                "t": row.t,
+                "trial": row.trial,
+                "fields": row.fields,
+            })
+    return out
+
+
+def to_dataframe(rows: Sequence[Dict[str, Any]]):
+    """
+    Convert a tidy table (a ``list[dict]``, e.g. from ``cycles_table()``)
+    into a pandas ``DataFrame``. Requires pandas to be installed
+    (``pip install sfm-analysis[pandas]``); raises a clear ``ImportError``
+    naming that extra if it isn't, rather than a bare
+    ``ModuleNotFoundError`` from deep inside pandas.
+    """
+    try:
+        import pandas as pd
+    except ImportError as exc:
+        raise ImportError(
+            "to_dataframe() needs pandas -- install it with "
+            "`pip install sfm-analysis[pandas]`"
+        ) from exc
+    return pd.DataFrame(list(rows))

sfm_analysis/cli/__init__.py

@@ -0,0 +1 @@
+"""cli — command-line entry points for sfm_analysis."""