straplog 0.2.0__py3-none-any.whl

straplog/__init__.py

@@ -0,0 +1,10 @@
+"""Read StrapLog exports: one single-file SQLite snapshot per recording.
+
+`straplog.export` reads a file as stored (epoch ms UTC, typed markers);
+`straplog.catalog` lists a folder of exports; `straplog.db` loads into the
+HRV skills' Apple-epoch local-time convention; `straplog.hrv` holds the
+format-agnostic HRV algorithms; `straplog.plot` is the house chart style
+(needs the `plot` extra); `straplog.cli` is the agent tool surface.
+The schema is docs/SCHEMA.md in the StrapLog app repo.
+"""
+__version__ = "0.2.0"

straplog/_sqlite.py

@@ -0,0 +1,26 @@
+"""Opening a StrapLog export safely."""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+
+def connect(db_path: Path) -> sqlite3.Connection:
+    """Open read-only and immutable: no -wal/-shm is ever created beside the
+    user's export."""
+    return sqlite3.connect(f"{Path(db_path).resolve().as_uri()}?immutable=1",
+                           uri=True)
+
+
+def require_snapshot(db_path: Path) -> None:
+    """A StrapLog -wal means the live database, which an immutable read would
+    see only partly. Exports are always single files."""
+    if Path(str(db_path) + "-wal").exists():
+        raise SystemExit(
+            f"{db_path} has a -wal sidecar, so it is StrapLog's live database. "
+            "Use an exported snapshot (iCloud Drive > StrapLog > <date>-<name>.sqlite, on the Mac "
+            "~/Library/Mobile Documents/iCloud~com~personalscience~straplog/Documents/).")
+
+
+def columns(con: sqlite3.Connection, table: str) -> set[str]:
+    return {r[1] for r in con.execute(f"PRAGMA table_info({table})")}

straplog/catalog.py

@@ -0,0 +1,67 @@
+"""Find recordings in a folder of exports: `index.json` first, then a scan.
+
+The app rewrites `index.json` after every export and delete (ExportIndex),
+so an agent reads one file instead of opening each snapshot. Exports the
+index does not list (older builds, files copied in from elsewhere) are
+read directly, each as the recording it is named after, so a folder without
+an index still lists completely and without duplicates.
+"""
+from __future__ import annotations
+
+import json
+import re
+import time
+from datetime import datetime
+from pathlib import Path
+
+from . import export
+
+DEFAULT_DIR = Path.home() / "Library/Mobile Documents/iCloud~com~personalscience~straplog/Documents"
+INDEX = "index.json"
+
+
+def entries(where: Path = DEFAULT_DIR) -> list[dict]:
+    """Index entries, newest first, each with `path` and `downloaded` added.
+    `where` is a folder of exports or a single export file."""
+    where = Path(where).expanduser()
+    if where.is_file():
+        return [_located(e, where.parent) for e in export.recordings(where)]
+    indexed = []
+    if (where / INDEX).exists():
+        indexed = json.loads((where / INDEX).read_text())["recordings"]
+    listed = {e["file"] for e in indexed}
+    scanned = [e for f in sorted(where.glob("*.sqlite")) if f.name not in listed
+               for e in export.recordings(f, named_only=True)]
+    rows = [_located(e, where) for e in indexed + scanned]
+    return sorted(rows, key=lambda e: (e["started_at_ms"], e["id"]), reverse=True)
+
+
+def select(rows: list[dict], activity: str | None = None, since: str | None = None,
+           limit: int | None = None, now_ms: int | None = None) -> list[dict]:
+    if activity:
+        rows = [e for e in rows if e["activity"] == activity]
+    if since:
+        cutoff = since_ms(since, now_ms if now_ms is not None else int(time.time() * 1000))
+        rows = [e for e in rows if e["started_at_ms"] >= cutoff]
+    return rows[:limit] if limit else rows
+
+
+def since_ms(since: str, now_ms: int) -> int:
+    """`14d`, `12h`, `90m` back from now, or an ISO date/time (local if naive)."""
+    m = re.fullmatch(r"(\d+)([dhm])", since)
+    if m:
+        return now_ms - int(m[1]) * {"d": 86_400_000, "h": 3_600_000, "m": 60_000}[m[2]]
+    return int(datetime.fromisoformat(since).astimezone().timestamp() * 1000)
+
+
+def resolve(file: str, folder: Path | None = None) -> Path:
+    """A path, or a bare export name looked up in `folder` (default DEFAULT_DIR)."""
+    p = Path(file).expanduser()
+    if p.exists() or p.parent != Path("."):
+        return p
+    return Path(folder or DEFAULT_DIR) / file
+
+
+def _located(entry: dict, folder: Path) -> dict:
+    path = folder / entry["file"]
+    return {**entry, "path": str(path), "downloaded": path.exists()}

straplog/cli.py

@@ -0,0 +1,101 @@
+"""`straplog`: the agent tool surface over StrapLog exports.
+
+    straplog ls [FOLDER|FILE] [--activity sleep] [--since 14d] [--limit N] [--json]
+    straplog rr FILE [--id N] [--json]          beats: t_ms, rr_ms
+    straplog events FILE [--id N] [--markers] [--json]
+    straplog meta FILE
+
+FILE is a path or a bare export name in the iCloud folder. Times are epoch ms
+UTC; local time = UTC + tz_offset_s (`ls` prints it as `started_local`).
+Tables print as CSV unless --json.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+
+from . import catalog, export
+
+LS_COLUMNS = ("started_local", "activity", "name", "duration_ms", "beats", "coverage", "labels", "file")
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _parser().parse_args(argv)
+    args.run(args)
+
+
+def _ls(args) -> None:
+    rows = catalog.select(catalog.entries(args.where), args.activity, args.since, args.limit)
+    if args.json:
+        _json(rows)
+    else:
+        _csv([{**r, "labels": " ".join(r["labels"])} for r in rows], LS_COLUMNS)
+
+
+def _rr(args) -> None:
+    _table(export.beats(_file(args), args.id), ("t_ms", "rr_ms"), args.json)
+
+
+def _events(args) -> None:
+    _table(export.events(_file(args), args.id, args.markers), ("at_ms", "kind", "label", "note"), args.json)
+
+
+def _meta(args) -> None:
+    path = _file(args)
+    _json({"meta": export.meta(path), "recordings": export.recordings(path)})
+
+
+def _file(args) -> Path:
+    path = catalog.resolve(args.file)
+    if not path.exists():
+        raise SystemExit(f"No such export: {path}")
+    return path
+
+
+def _table(rows: list[dict], cols: tuple[str, ...], as_json: bool) -> None:
+    _json(rows) if as_json else _csv(rows, cols)
+
+
+def _json(value) -> None:
+    json.dump(value, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+def _csv(rows: list[dict], cols: tuple[str, ...]) -> None:
+    w = csv.DictWriter(sys.stdout, cols, extrasaction="ignore", lineterminator="\n")
+    w.writeheader()
+    w.writerows(rows)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="straplog", description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = p.add_subparsers(required=True, metavar="COMMAND")
+
+    ls = sub.add_parser("ls", help="list recordings, newest first")
+    ls.add_argument("where", nargs="?", type=Path, default=catalog.DEFAULT_DIR,
+                    help="folder of exports or one export (default: the iCloud folder)")
+    ls.add_argument("--activity", help="e.g. sleep, other")
+    ls.add_argument("--since", help="14d, 12h, 90m, or an ISO date")
+    ls.add_argument("--limit", type=int)
+    ls.add_argument("--json", action="store_true")
+    ls.set_defaults(run=_ls)
+
+    for name, run, help_ in (("rr", _rr, "beats: t_ms, rr_ms"),
+                             ("events", _events, "events: at_ms, kind, label, note"),
+                             ("meta", _meta, "meta table and index entry, as JSON")):
+        c = sub.add_parser(name, help=help_)
+        c.add_argument("file")
+        c.set_defaults(run=run)
+        if name != "meta":
+            c.add_argument("--id", type=int, help="recording id (only for multi-recording files)")
+            c.add_argument("--json", action="store_true")
+    sub.choices["events"].add_argument("--markers", action="store_true", help="markers only")
+    return p
+
+
+if __name__ == "__main__":
+    main()

straplog/db.py

@@ -0,0 +1,183 @@
+"""Read a StrapLog export in the HRV Logger loaders' conventions.
+
+StrapLog (the Polar H10 logger in ~/dev/iOS Projects/StrapLog) writes a
+single-file SQLite snapshot: `recording`, `notification`, `beat`, `event`,
+`motion`, `meta` (its docs/SCHEMA.md is the source of truth). Its times are
+Unix epoch ms UTC plus a per-recording `tz_offset_s`.
+
+The HRV Logger loaders in these skills work in Apple-epoch seconds of LOCAL
+wall-clock (Core Data stored local time as if it were UTC). This module maps
+StrapLog onto that convention, so every analysis downstream is unchanged:
+
+    t = (t_end_ms_est / 1000 + tz_offset_s) - 978307200
+
+Skills import it as `import straplog.db as straplog_db`; this replaced the
+copies `_hrv_shared/sync.sh` used to push into each skill's scripts/.
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from ._sqlite import columns, connect as _connect, require_snapshot as _require_snapshot
+
+APPLE_EPOCH_OFFSET = 978307200.0   # 2001-01-01 -> unix
+# Consecutive H10 notifications arrive ~1 s apart; a longer silence is a
+# Bluetooth dropout, and that time counts against coverage.
+NOTIFICATION_GAP_SEC = 3.0
+
+
+def is_straplog(db_path: Path) -> bool:
+    """True for a StrapLog file (it has a `beat` table); False for HRV Logger."""
+    con = _connect(db_path)
+    try:
+        return con.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='beat'"
+        ).fetchone() is not None
+    finally:
+        con.close()
+
+
+def _local_apple(ms, tz_offset_s):
+    return ms / 1000.0 + tz_offset_s - APPLE_EPOCH_OFFSET
+
+
+def _recording(con: sqlite3.Connection, rid: int) -> dict:
+    row = con.execute(
+        "SELECT name, started_at_ms, ended_at_ms, tz_offset_s FROM recording "
+        "WHERE id=?", (rid,)).fetchone()
+    if row is None:
+        raise SystemExit(f"Recording {rid} not found.")
+    return dict(zip(("name", "started_at_ms", "ended_at_ms", "tz_offset_s"), row))
+
+
+def _coverage(received_ms: np.ndarray, start_ms: int, end_ms: int) -> float | None:
+    """Fraction of the recording's wall-clock span covered by notifications:
+    the sum of inter-notification intervals no longer than
+    NOTIFICATION_GAP_SEC, over end - start. Time before the first and after
+    the last notification is uncovered."""
+    span = end_ms - start_ms
+    if span <= 0 or received_ms.size < 2:
+        return None
+    d = np.diff(received_ms)
+    return float(d[d <= NOTIFICATION_GAP_SEC * 1000].sum() / span)
+
+
+def coverage(db_path: Path, rid: int) -> float | None:
+    _require_snapshot(db_path)
+    con = _connect(db_path)
+    try:
+        rec = _recording(con, rid)
+        rx = np.array([r[0] for r in con.execute(
+            "SELECT received_at_ms FROM notification WHERE recording_id=? "
+            "ORDER BY id", (rid,))], dtype=float)
+    finally:
+        con.close()
+    end = rec["ended_at_ms"] or (int(rx[-1]) if rx.size else rec["started_at_ms"])
+    return _coverage(rx, rec["started_at_ms"], end)
+
+
+def list_recordings(db_path: Path) -> list[dict]:
+    """One dict per recording with the keys the HRV Logger listers share:
+    pk, name, start_local (ISO, local wall-clock), n_beats, duration_min,
+    avg_hr, coverage. Each skill adds its own extra keys."""
+    _require_snapshot(db_path)
+    con = _connect(db_path)
+    try:
+        recs = con.execute(
+            "SELECT id, name, started_at_ms, ended_at_ms, tz_offset_s "
+            "FROM recording ORDER BY started_at_ms").fetchall()
+        beats = {r[0]: r[1:] for r in con.execute(
+            "SELECT recording_id, COUNT(*), AVG(rr_ms) FROM beat "
+            "GROUP BY recording_id")}
+        rx: dict[int, list[int]] = {}
+        for rid, ms in con.execute(
+                "SELECT recording_id, received_at_ms FROM notification ORDER BY id"):
+            rx.setdefault(rid, []).append(ms)
+    finally:
+        con.close()
+
+    out = []
+    for rid, name, start_ms, end_ms, tz in recs:
+        n, mean_rr = beats.get(rid, (0, None))
+        r = np.array(rx.get(rid, []), dtype=float)
+        end = end_ms or (int(r[-1]) if r.size else start_ms)
+        cov = _coverage(r, start_ms, end)
+        out.append({
+            "pk": rid,
+            "name": name or "",
+            "start_local": pd.to_datetime(start_ms + tz * 1000, unit="ms").isoformat(),
+            "n_beats": int(n),
+            "duration_min": round((end - start_ms) / 60000.0, 1),
+            "avg_hr": round(60000.0 / mean_rr, 1) if mean_rr else None,
+            "coverage": None if cov is None else round(cov, 3),
+        })
+    return out
+
+
+def load_rr(db_path: Path, rid: int) -> pd.DataFrame:
+    """Beats as DataFrame[t, rr_ms], t in Apple-epoch local seconds.
+
+    Ordered by beat id (true beat order). The H10 sends no beat timestamps, so
+    `t_end_ms_est` is anchored on phone receipt, and BLE delivery jitter
+    leaves ~2 % of beats up to ~0.9 s earlier than the beat before. `t` is
+    clamped non-decreasing so window and gap logic never sees time run
+    backwards; rr_ms itself is exact.
+    """
+    _require_snapshot(db_path)
+    con = _connect(db_path)
+    try:
+        tz = _recording(con, rid)["tz_offset_s"]
+        rr = pd.read_sql_query(
+            "SELECT t_end_ms_est AS t, rr_ms FROM beat WHERE recording_id=? "
+            "ORDER BY id", con, params=(rid,))
+    finally:
+        con.close()
+    rr["t"] = _local_apple(rr["t"].astype(float).cummax(), tz)
+    return rr
+
+
+def load_events(db_path: Path, rid: int) -> pd.DataFrame:
+    """User markers as DataFrame[t, note]: StrapLog's `marker` events, which
+    are what HRV Logger's ZEVENT rows were. Lifecycle events (start, connect,
+    snapshot, ...) are not user notes and are left out.
+
+    From schema v3 a marker has a preset `label` (`a`, `awake`, ...), a free
+    `note`, or both; `note` here is the label, then ` · note` if both, which
+    matches v2 files where the label was the note."""
+    _require_snapshot(db_path)
+    con = _connect(db_path)
+    try:
+        tz = _recording(con, rid)["tz_offset_s"]
+        cols = columns(con, "event")
+        text = ("COALESCE(label || COALESCE(' · ' || note, ''), note, '')"
+                if "label" in cols else "COALESCE(note, '')")
+        ev = pd.read_sql_query(
+            f"SELECT at_ms AS t, {text} AS note FROM event "
+            "WHERE recording_id=? AND kind='marker' ORDER BY at_ms",
+            con, params=(rid,))
+    finally:
+        con.close()
+    ev["t"] = _local_apple(ev["t"].astype(float), tz)
+    return ev
+
+
+def load_recording(db_path: Path, rid: int):
+    """(rr[t, rr_ms, t_rel], ev[t, note, t_rel], start_local, name), the shape
+    of h10-session's HRV Logger `load_recording`. t_rel is seconds from the
+    first beat; start_local is a naive local-wall-clock Timestamp."""
+    rr = load_rr(db_path, rid)
+    ev = load_events(db_path, rid)
+    con = _connect(db_path)
+    try:
+        name = _recording(con, rid)["name"] or ""
+    finally:
+        con.close()
+    t0 = rr["t"].iloc[0] if len(rr) else 0.0
+    rr["t_rel"] = rr["t"] - t0
+    ev["t_rel"] = ev["t"] - t0
+    start_local = pd.to_datetime(t0 + APPLE_EPOCH_OFFSET, unit="s")
+    return rr, ev, start_local, name

straplog/export.py

@@ -0,0 +1,151 @@
+"""One StrapLog export as stored: epoch ms UTC, typed markers.
+
+Snapshots hold one recording each (the app's `Snapshot`). Exports from
+before that held every recording on the phone; the file is still named after
+one of them (`file_name`), and that one is the default everywhere. Every
+reader also takes a recording id.
+Schema v2 files have no `activity`, `context` or `event.label`; they read
+as activity `other` with labels left in `note`, as the app's v3 migration does.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from ._sqlite import columns, connect, require_snapshot
+
+# Must match Coverage.defaultGapThresholdMs in StrapLogCore.
+GAP_THRESHOLD_MS = 3000
+# meta values the app writes as JSON (ExportMeta).
+JSON_META = ("preset", "event_kinds")
+
+
+def meta(path: Path) -> dict:
+    """The `meta` table, with ExportMeta's JSON values decoded."""
+    with _open(path) as con:
+        rows = dict(con.execute("SELECT key, value FROM meta"))
+    for k in JSON_META:
+        if k in rows:
+            rows[k] = json.loads(rows[k])
+    return rows
+
+
+def recordings(path: Path, named_only: bool = False) -> list[dict]:
+    """One `index.json` entry (ExportIndexEntry) per recording, newest first,
+    computed from the file itself. `named_only` keeps just the recording the
+    file is named after, when there is one."""
+    path = Path(path)
+    with _open(path) as con:
+        recs = _recordings(con)
+        if named_only:
+            recs = [r for r in recs if r[0] == _named(recs, path)] or recs
+        out = []
+        for rid, name, act, start, end, tz in recs:
+            (n,) = con.execute("SELECT COUNT(*) FROM beat WHERE recording_id=?", (rid,)).fetchone()
+            entry = {
+                "file": path.name, "id": rid, "name": name, "activity": act,
+                "started_at_ms": start, "ended_at_ms": end, "tz_offset_s": tz,
+                "started_local": _local_iso(start, tz),
+                "duration_ms": None if end is None else end - start,
+                "beats": n, "coverage": round(_app_coverage(con, rid), 4),
+                "labels": [e["label"] for e in _events(con, rid, markers_only=True) if e["label"]],
+            }
+            out.append({k: v for k, v in entry.items() if v is not None})
+    return out
+
+
+def file_name(name: str, started_at_ms: int, tz_offset_s: int) -> str:
+    """StrapLogCore's `Snapshot.fileName`: `YYMMDD-HHMM-<name>.sqlite` in the
+    recording's local time, the name's other characters replaced by `_`."""
+    local = datetime.fromtimestamp(started_at_ms / 1000 + tz_offset_s, timezone.utc)
+    safe = "".join(c if c.isalnum() or c in "-_" else "_" for c in name)
+    stamp = local.strftime("%y%m%d-%H%M")
+    return f"{stamp}-{safe}.sqlite" if safe else f"{stamp}.sqlite"
+
+
+def beats(path: Path, rid: int | None = None) -> list[dict]:
+    """Beats in true order: `t_ms` (estimated beat end, epoch ms UTC) and
+    `rr_ms` (exact). The H10 sends no beat times, so `t_ms` is anchored on
+    phone receipt and clamped non-decreasing against BLE delivery jitter."""
+    with _open(path) as con:
+        rid = _one_recording(con, rid, path)
+        rows = con.execute("SELECT t_end_ms_est, rr_ms FROM beat WHERE recording_id=? "
+                           "ORDER BY id", (rid,)).fetchall()
+    out, last = [], None
+    for t, rr in rows:
+        last = t if last is None else max(last, t)
+        out.append({"t_ms": last, "rr_ms": rr})
+    return out
+
+
+def events(path: Path, rid: int | None = None, markers_only: bool = False) -> list[dict]:
+    """Events in time order: `at_ms`, `kind`, `label` (v3 markers), `note`."""
+    with _open(path) as con:
+        return _events(con, _one_recording(con, rid, path), markers_only)
+
+
+def _events(con: sqlite3.Connection, rid: int, markers_only: bool) -> list[dict]:
+    label = "label" if "label" in columns(con, "event") else "NULL"
+    where = " AND kind='marker'" if markers_only else ""
+    return [dict(zip(("at_ms", "kind", "label", "note"), r)) for r in con.execute(
+        f"SELECT at_ms, kind, {label}, note FROM event WHERE recording_id=?{where} "
+        "ORDER BY at_ms, id", (rid,))]
+
+
+def _app_coverage(con: sqlite3.Connection, rid: int) -> float:
+    """StrapLogCore's `Coverage.fraction`: first-to-last notification span
+    minus silences over GAP_THRESHOLD_MS, over that span; 0 if empty. (The
+    HRV skills' `straplog.db.coverage` divides by the recording span instead.)"""
+    t = [r[0] for r in con.execute("SELECT received_at_ms FROM notification "
+                                   "WHERE recording_id=? ORDER BY received_at_ms", (rid,))]
+    span = t[-1] - t[0] if len(t) > 1 else 0
+    if span <= 0:
+        return 0.0
+    gaps = sum(b - a for a, b in zip(t, t[1:]) if b - a > GAP_THRESHOLD_MS)
+    return (span - gaps) / span
+
+
+def _recordings(con: sqlite3.Connection) -> list[tuple]:
+    """(id, name, activity, started_at_ms, ended_at_ms, tz_offset_s), newest first."""
+    activity = "activity" if "activity" in columns(con, "recording") else "'other'"
+    return con.execute(
+        f"SELECT id, name, {activity}, started_at_ms, ended_at_ms, tz_offset_s "
+        "FROM recording ORDER BY started_at_ms DESC, id DESC").fetchall()
+
+
+def _named(recs: list[tuple], path: Path) -> int | None:
+    """The id of the recording `path` is named after, if any."""
+    return next((r[0] for r in recs if file_name(r[1], r[3], r[5]) == Path(path).name), None)
+
+
+def _one_recording(con: sqlite3.Connection, rid: int | None, path: Path) -> int:
+    recs = _recordings(con)
+    ids = sorted(r[0] for r in recs)
+    if rid is None:
+        rid = ids[0] if len(ids) == 1 else _named(recs, path)
+        if rid is None:
+            raise SystemExit(f"File holds recordings {ids}; pick one with --id.")
+    if rid not in ids:
+        raise SystemExit(f"Recording {rid} not found; the file holds {ids}.")
+    return rid
+
+
+def _local_iso(ms: int, tz_offset_s: int) -> str:
+    """ISO 8601 with offset, as Swift's ISO8601DateFormatter writes it."""
+    dt = datetime.fromtimestamp(ms / 1000, timezone(timedelta(seconds=tz_offset_s)))
+    return dt.replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+@contextmanager
+def _open(path: Path) -> Iterator[sqlite3.Connection]:
+    """A checked, immutable, read-only connection."""
+    require_snapshot(path)
+    con = connect(path)
+    try:
+        yield con
+    finally:
+        con.close()

straplog/hrv.py

@@ -0,0 +1,147 @@
+"""HRV algorithms over RR intervals in ms. Format-agnostic: nothing here
+knows about StrapLog files, so it works on any RR series.
+
+One copy of what the H10 skills (h10-session, hrv-overnight, hrv-ramp-test,
+hrv-resting) each used to carry: the artifact filter, time-domain metrics,
+DFA alpha1 and the sliding-window feature table.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+RR_MIN_MS = 300.0           # physiological gate: 200 bpm
+RR_MAX_MS = 2000.0          # 30 bpm
+PCT_THRESH_DEFAULT = 0.25   # workout; resting readings use a stricter 0.20
+
+DFA_SCALE_MIN = 4           # short-term alpha1 box sizes, in beats
+DFA_SCALE_MAX = 16
+
+WINDOW_SEC_DEFAULT = 120.0
+STRIDE_SEC_DEFAULT = 60.0
+MIN_BEATS_PER_WIN = 60
+
+
+def artifact_mask(rr_ms, pct_thresh: float = PCT_THRESH_DEFAULT) -> np.ndarray:
+    """Boolean keep-mask over the input beats: physiological gate, then an
+    iterative (up to 3 passes) 5-beat median filter dropping beats more than
+    `pct_thresh` from the local median. In the spirit of Altini's 'Workout'
+    correction: salvages high-HR segments without erasing real variability.
+
+    A mask rather than the filtered values, so callers can carry per-beat
+    timestamps through the filter and slice by time afterwards."""
+    x = np.asarray(rr_ms, dtype=float).copy()
+    x[(x < RR_MIN_MS) | (x > RR_MAX_MS)] = np.nan
+    for _ in range(3):
+        s = pd.Series(x)
+        med = s.rolling(5, center=True, min_periods=3).median()
+        bad = ((s - med).abs() / med) > pct_thresh
+        if not bad.any():
+            break
+        x[bad.to_numpy()] = np.nan
+    return ~np.isnan(x)
+
+
+def clean_rr(rr_ms, pct_thresh: float = PCT_THRESH_DEFAULT) -> np.ndarray:
+    """The beats `artifact_mask` keeps."""
+    x = np.asarray(rr_ms, dtype=float)
+    return x[artifact_mask(x, pct_thresh)]
+
+
+def time_domain(rr_ms) -> dict:
+    """Time-domain HRV over already-cleaned RR intervals (ms). SDNN, SDSD and
+    HR SD are sample statistics (ddof=1), the HRV-literature convention.
+    Fewer than 2 beats gives NaN for everything but n."""
+    rr = np.asarray(rr_ms, dtype=float)
+    n = int(rr.size)
+    if n < 2:
+        return {"n": n} | dict.fromkeys(
+            ("mean_rr_ms", "hr_mean", "hr_sd", "hr_min", "hr_max", "sdnn_ms",
+             "rmssd_ms", "ln_rmssd", "pnn50_pct", "sdsd_ms"), float("nan"))
+    d = np.diff(rr)
+    hr = 60000.0 / rr
+    rmssd = float(np.sqrt(np.mean(d ** 2)))
+    return {
+        "n": n,
+        "mean_rr_ms": float(rr.mean()),
+        "hr_mean": float(hr.mean()),     # mean of beat HRs, not 60000/mean_rr_ms
+        "hr_sd": float(hr.std(ddof=1)),
+        "hr_min": float(hr.min()),
+        "hr_max": float(hr.max()),
+        "sdnn_ms": float(rr.std(ddof=1)),
+        "rmssd_ms": rmssd,
+        "ln_rmssd": float(np.log(rmssd)) if rmssd > 0 else float("nan"),
+        "pnn50_pct": float(100.0 * np.mean(np.abs(d) > 50)),
+        "sdsd_ms": float(d.std(ddof=1)) if d.size > 1 else float("nan"),
+    }
+
+
+def dfa_alpha1(rr_ms, scale_min: int = DFA_SCALE_MIN,
+               scale_max: int = DFA_SCALE_MAX) -> float:
+    """Short-term detrended fluctuation exponent (alpha1) of a cleaned RR
+    series; NaN when there are too few beats to fit the scales."""
+    rr = np.asarray(rr_ms, dtype=float)
+    n_total = len(rr)
+    if n_total < scale_max * 4:
+        return np.nan
+
+    y = np.cumsum(rr - rr.mean())
+    scales = np.arange(scale_min, scale_max + 1)
+    F = np.full(len(scales), np.nan)
+
+    for i, n in enumerate(scales):
+        nb = n_total // n
+        if nb < 4:
+            continue
+        segs = y[: nb * n].reshape(nb, n)
+        x = np.arange(n)
+        x_mean = x.mean()
+        x_var = ((x - x_mean) ** 2).sum()
+        seg_mean = segs.mean(axis=1, keepdims=True)
+        cov = ((segs - seg_mean) * (x - x_mean)).sum(axis=1) / x_var
+        intercept = seg_mean.squeeze() - cov * x_mean
+        trend = np.outer(cov, x) + intercept[:, None]
+        F[i] = np.sqrt(((segs - trend) ** 2).mean())
+
+    mask = np.isfinite(F) & (F > 0)
+    if mask.sum() < 4:
+        return np.nan
+    slope, _ = np.polyfit(np.log(scales[mask]), np.log(F[mask]), 1)
+    return float(slope)
+
+
+def rolling_features(rr_df: pd.DataFrame,
+                     window_sec: float = WINDOW_SEC_DEFAULT,
+                     stride_sec: float = STRIDE_SEC_DEFAULT,
+                     pct_thresh: float = PCT_THRESH_DEFAULT,
+                     min_beats: int = MIN_BEATS_PER_WIN) -> pd.DataFrame:
+    """Sliding windows over rr_df[t_rel, rr_ms], anchored at t_rel=0.
+    Artifact correction runs per window, so a burst of bad beats doesn't drag
+    a neighbouring window. Columns: t_center, t_min, hr_bpm, alpha1, rmssd,
+    n_beats, n_raw. Windows with fewer than `min_beats` beats are skipped."""
+    t_end = rr_df["t_rel"].max()
+    centers = np.arange(window_sec / 2, t_end - window_sec / 2 + 1, stride_sec)
+    t_arr = rr_df["t_rel"].to_numpy()
+    rr_arr = rr_df["rr_ms"].to_numpy()
+
+    rows = []
+    for c in centers:
+        lo, hi = c - window_sec / 2, c + window_sec / 2
+        raw = rr_arr[(t_arr >= lo) & (t_arr < hi)]
+        if raw.size < min_beats:
+            continue
+        clean = clean_rr(raw, pct_thresh)
+        if clean.size < min_beats:
+            continue
+        d = np.diff(clean)
+        rows.append({
+            "t_center": c,
+            "t_min": c / 60.0,
+            "hr_bpm": 60000.0 / clean.mean(),
+            "alpha1": dfa_alpha1(clean),
+            "rmssd": float(np.sqrt((d ** 2).mean())) if d.size else np.nan,
+            "n_beats": clean.size,
+            "n_raw": raw.size,
+        })
+    return pd.DataFrame(rows, columns=["t_center", "t_min", "hr_bpm", "alpha1",
+                                       "rmssd", "n_beats", "n_raw"])

straplog/plot.py

@@ -0,0 +1,129 @@
+"""
+House chart style for the H10 skills (plotnine): system-sans typography, a
+recessive grid, hairline axes, and a validated categorical palette.
+Needs the `plot` extra: `pip install straplog[plot]`.
+
+    from straplog import plot as chart_style
+    from plotnine import ggplot, aes, geom_line
+    p = (ggplot(df, aes("x", "y"))
+         + geom_line(color=chart_style.SERIES["blue"])
+         + chart_style.theme_house())
+    p.save(path, dpi=chart_style.DPI, width=..., height=..., verbose=False)
+
+plotnine has no global rcParams: every ``ggplot`` needs
+``+ chart_style.theme_house()`` and every ``.save()`` an explicit
+``dpi=chart_style.DPI``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from plotnine import (
+    aes, annotate, element_blank, element_line, element_rect, element_text,
+    theme, theme_minimal,
+)
+
+# ---------- palette --------------------------------------------------------
+# Categorical slots in fixed order. Assign by slot, never cycle: the ordering
+# is what keeps adjacent pairs distinguishable under colour-vision deficiency.
+
+SERIES = {
+    "blue":    "#2a78d6",
+    "green":   "#008300",
+    "magenta": "#e87ba4",
+    "yellow":  "#eda100",
+    "aqua":    "#1baf7a",
+    "orange":  "#eb6834",
+    "violet":  "#4a3aa7",
+    "red":     "#e34948",
+}
+SERIES_ORDER = list(SERIES.values())
+
+# Chrome and text. Series colours identify marks; text stays in ink.
+INK = {
+    "surface":   "#fcfcfb",
+    "primary":   "#0b0b0b",   # titles
+    "secondary": "#52514e",   # axis titles, annotations
+    "muted":     "#898781",   # tick labels, de-emphasised marks
+    "grid":      "#e1e0d9",
+    "baseline":  "#c3c2b7",   # axis spines / reference lines
+}
+
+# Reserved for state, never for a series.
+STATUS = {
+    "good":     "#0ca30c",
+    "warning":  "#fab219",
+    "serious":  "#ec835a",
+    "critical": "#d03b3b",
+}
+
+# HR training-zone bands (Z1..Z5), painted as backgrounds behind the trace.
+# Cool->warm rather than a single-hue ramp: "hot = hard" is the training
+# convention and carries real meaning here. Chroma is held low so the bands
+# stay behind the data. Use at full opacity - alpha is baked into these steps.
+ZONE_BANDS = ["#eef4fb", "#e9f3ec", "#fbf4e2", "#fbeade", "#fae4e4"]
+
+# Sequential blue ramp, light -> dark, for continuous magnitude.
+SEQUENTIAL_BLUE = [
+    "#cde2fb", "#9ec5f4", "#6da7ec", "#3987e5",
+    "#2a78d6", "#256abf", "#184f95", "#0d366b",
+]
+
+FONT_FAMILY = "Helvetica Neue"   # falls back per-system font resolution
+DPI = 150                        # pass explicitly to every p.save(...)
+
+
+def theme_house(base_size: int = 10):
+    """The plotnine equivalent of the old apply(): chain onto every ggplot."""
+    return theme_minimal(base_size=base_size) + theme(
+        text=element_text(family=FONT_FAMILY, color=INK["primary"]),
+        plot_title=element_text(size=base_size * 1.3, weight="bold",
+                                color=INK["primary"]),
+        axis_title=element_text(size=base_size, color=INK["secondary"]),
+        axis_text=element_text(size=base_size * 0.9, color=INK["muted"]),
+        plot_background=element_rect(fill=INK["surface"], color=INK["surface"]),
+        panel_background=element_rect(fill=INK["surface"], color=INK["surface"]),
+        panel_grid_major=element_line(color=INK["grid"], linewidth=0.6),
+        panel_grid_minor=element_blank(),
+        axis_ticks=element_blank(),
+        legend_background=element_blank(),
+        legend_key=element_blank(),
+        legend_title=element_text(size=base_size * 0.9, color=INK["secondary"]),
+        legend_text=element_text(size=base_size * 0.9, color=INK["secondary"]),
+        strip_background=element_blank(),
+    )
+
+
+# ---------- shared layer helpers -------------------------------------------
+
+def zone_band_layers(zones, hr_max: float, hr_rest: float):
+    """zones: list of (name, lo_frac, hi_frac) Karvonen tuples, e.g. the
+    ZONES constant each analysis script already defines. Returns a list of
+    ``annotate("rect", ...)`` layers, cool->warm, meant to be added first so
+    they render behind the data (mirrors the old ax.axhspan loop)."""
+    reserve = max(1.0, hr_max - hr_rest)
+    layers = []
+    for (_name, lo, hi), color in zip(zones, ZONE_BANDS):
+        y_lo = hr_rest + lo * reserve
+        y_hi = hr_rest + hi * reserve
+        layers.append(annotate("rect", xmin=-np.inf, xmax=np.inf,
+                                ymin=y_lo, ymax=y_hi, fill=color))
+    return layers
+
+
+def event_marker_layers(ev_df, x_col: str = "t_min", label_col: str = None,
+                        y_top: float = None, color: str = None):
+    """Vertical dotted lines for each row in ev_df (an events dataframe with
+    at least an x_col), mirroring the old per-row ax.axvline + optional rotated
+    ax.text. If label_col is given, adds rotated top-anchored text -- y_top must
+    be supplied (plotnine has no "top of current axis" primitive; the caller
+    computes the y-range from the data first, e.g. ``feat['hr_bpm'].max()``)."""
+    from plotnine import geom_text, geom_vline
+    color = color or INK["baseline"]
+    layers = [geom_vline(data=ev_df, mapping=aes(xintercept=x_col),
+                         color=color, linetype="dotted", size=0.9)]
+    if label_col and y_top is not None:
+        layers.append(geom_text(data=ev_df, mapping=aes(x=x_col, label=label_col),
+                                y=y_top, angle=90, ha="left", va="top",
+                                size=7, color=color))
+    return layers

straplog-0.2.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: straplog
+Version: 0.2.0
+Summary: Read StrapLog exports (Polar H10 RR intervals in SQLite) and compute HRV: library and CLI.
+Project-URL: Homepage, https://github.com/personalscience/straplog-py
+Author: Richard Sprague
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dfa-alpha1,heart-rate-variability,hrv,polar-h10,rr-intervals
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Requires-Dist: numpy
+Requires-Dist: pandas
+Provides-Extra: plot
+Requires-Dist: plotnine; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# straplog
+
+Read [StrapLog](https://github.com/personalscience) exports and compute heart-rate variability.
+
+StrapLog is an iOS app that records beat-to-beat RR intervals from a Polar H10 chest strap. It writes each recording as one self-contained SQLite file (`<YYMMDD-HHMM>-<name>.sqlite`) to its iCloud folder, plus an `index.json` catalog. This package reads those files and provides the HRV algorithms used by the StrapLog Claude Code skills.
+
+## Install
+
+```sh
+uv add straplog            # or: pip install straplog
+uv add 'straplog[plot]'    # + the plotnine house chart style
+```
+
+## Use
+
+```python
+from straplog import db, hrv
+
+recs = db.list_recordings("251018-0712-REST.sqlite")
+rr, events, start_local, name = db.load_recording("251018-0712-REST.sqlite", recs[0]["pk"])
+
+clean = hrv.clean_rr(rr["rr_ms"], pct_thresh=0.20)
+hrv.time_domain(clean)        # n, hr_mean, sdnn_ms, rmssd_ms, ln_rmssd, pnn50_pct, ...
+hrv.dfa_alpha1(clean)
+hrv.rolling_features(rr)      # 2-min windows, 1-min stride: hr_bpm, alpha1, rmssd
+```
+
+| Module | Role |
+|---|---|
+| `straplog.export` | A file as stored: epoch ms UTC, typed events |
+| `straplog.catalog` | List a folder of exports via `index.json` |
+| `straplog.db` | Load beats and markers as DataFrames in local time |
+| `straplog.hrv` | Artifact filter, time-domain metrics, DFA α1, sliding windows. Works on any RR series |
+| `straplog.plot` | House chart style (plotnine; `plot` extra) |
+| `straplog.cli` | `straplog ls / rr / events / meta` |
+
+## CLI
+
+```sh
+straplog ls --activity sleep --since 14d
+straplog rr 251018-0712-REST --json
+straplog events 251018-0712-REST --markers
+```
+
+A bare export name resolves against the StrapLog iCloud folder.
+
+## Conventions
+
+- RR in ms. The H10 sends RR in 1/1024 s; `rr_1024` is canonical in the file and `rr_ms` is derived.
+- SDNN, SDSD and HR SD are sample statistics (ddof=1). `hr_mean` is the mean of per-beat HR, not `60000 / mean_rr_ms`.
+- The artifact filter applies a 300–2000 ms gate, then an iterative 5-beat median filter. The default threshold is 0.25 (workouts); use 0.20 for resting readings.
+
+## License
+
+MIT

straplog-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+straplog/__init__.py,sha256=LYWfbA7CJErKb4gSESt_Kc0kL11TgVgYqHoYQuG6Feg,515
+straplog/_sqlite.py,sha256=KmfNObKVaPv1JXxdmyFiSaM-CxWWQSFkdD2G1VAyCZc,1041
+straplog/catalog.py,sha256=FUWt0AHU5-PbMTbvoJ7_5hcSwkaa4YcWIl0OoQDXv38,2737
+straplog/cli.py,sha256=lyXJoS6IQdfem96nvhVe4QZGHnhEAUoCT5QuaF8imAM,3471
+straplog/db.py,sha256=_7S_pM034c9wIhjj0Vu62Uynf4D4Vl2pfOP1pO1Z0Yo,7191
+straplog/export.py,sha256=lftH1rKqCjprOuCc4G2b0za8NiBtvmj8JCcujK0wVLs,6538
+straplog/hrv.py,sha256=pfSgywsnd4p3sKBQ7TkOUXzPRciU43jNfcAcsSfYb40,5751
+straplog/plot.py,sha256=admt_6BccJkV-EnVPY0dH_lTaHGK1BvpY90cJBbExBQ,5476
+straplog-0.2.0.dist-info/METADATA,sha256=mnbaeHsfPyS0CpA2Sc4G5oQtqxwmST_oMMvwKYlmsTA,2818
+straplog-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+straplog-0.2.0.dist-info/entry_points.txt,sha256=3SZ854FhYa2gmW2j7UPBMs8Znt9vUSaKWVTm7Ri8qNQ,47
+straplog-0.2.0.dist-info/licenses/LICENSE,sha256=XK9ghHHPPHRHgA-C8F9Y4IQx7rloGHGuDc1ZK4w0eLU,1097
+straplog-0.2.0.dist-info/RECORD,,

straplog-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

straplog-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+straplog = straplog.cli:main

straplog-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Sprague / Personal Science, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.