"""F0 case study: onset timing of forearm EMG, hand motion and fingertip contact. Descriptive CPU analysis on the public data (no training, no split, no seed):: python -m pulse.tasks.f0 --root $PULSE_ROOT --config configs/f0/grasp_timing.yaml \ --out runs/f0 [--workers 8] python figures/f0/plot_f0.py --in runs/f0 --out figures/out --tables tables Recordings: every S1-S8 recording whose EMG, pressure and skeleton MoCap pass the strict loaders (frozen availability table; the loaded list is checked against it). The Myo armband is on the RIGHT forearm of every volunteer, so contact events are taken from the right hand only (``hands: [right]``; the earlier analysis also paired left-hand contacts with right-forearm EMG). Per recording (100 Hz), the three streams are placed on the alignment timeline (the re-trimmed EMG / pressure files of v2s6, v13s2 and v13s3 start at their release offset; ``pulse.tasks.t2_data.recording_timeline``) and cut to the frames all three cover; then: * contact = sum of the 25 right-hand pressure cells; a contact onset is an upward crossing of ``pressure_threshold_g`` that stays above it for ``persist_frac`` of the next ``min_duration`` frames, at least ``min_gap`` frames after the previous onset (hysteresis release as in the original); * EMG envelope = per-channel rectified (mean-removed) signal, moving average of ``emg_envelope.window`` frames, summed over the 8 channels, min-max scaled over the recording; * motion = speed of the skeleton ``RightHand`` segment (frame difference of its X/Y/Z position, moving average of ``velocity.smooth_window`` frames); * an event is used if the ``context_sec`` before contact lies inside the recording, does not overlap a MoCap edge-filled stretch (``alignment_metadata.json`` warnings) or an untracked hand frame (non-finite or exactly zero position; such frames are linearly interpolated before the speed is computed), starts from rest (``clean`` rule: EMG and speed in the rest window are clearly below their pre-contact level), and both onsets are found and fall in ``delay_range_ms``; * onset of a signal = start of the last supra-threshold run before contact, threshold = baseline + ``threshold_ratio`` x (peak - baseline), baseline = ``baseline_percentile`` of the first ``baseline_frac`` of the pre-contact window. Statistics: per signal n, mean, SD (ddof=1), median, quartiles, IQR; paired motion - EMG difference per event (mean, SD, median, t-based 95 % CI, paired t, Wilcoxon signed-rank, share of events with motion first, Pearson r); the same comparison at volunteer level (per-volunteer medians: Wilcoxon and t over volunteers) with volunteer-bootstrap CIs, each paired with its own point estimate: the median of the per-volunteer median differences, and the pooled event-level median difference (volunteers as clusters). Caveat recorded in the output: EMG stream start times in alignment_metadata.json have whole-second resolution, which bounds the absolute EMG timing accuracy. Outputs in ``--out``: ``f0_timing.json`` (statistics, counts, provenance), ``f0_events.csv`` (one row per used event), ``f0_traces.npz`` (aligned pressure / EMG-envelope / speed windows of the used events). """ from __future__ import annotations import argparse import csv import json import math import os import re import sys import time from concurrent.futures import ProcessPoolExecutor from pathlib import Path from typing import Dict, List, Optional, Sequence import numpy as np from .. import DATA_TAG, __version__ from ..config import load_config from ..data.availability import Availability, default_availability_path from ..data.io import load_alignment_metadata, load_stream, modality_from_stream from ..data.manifest import expected_manifest, verify_loaded from ..data.recordings import SCENARIOS_TASK from ..errors import DataQualityError, ModalityUnavailableError, ProvenanceError from ..paths import DataRoot, split_rid from ..provenance import git_state, json_md5, now, relpath_or_name from ..splits import FoldSplit from .common import REPO_ROOT SR = 100 SCHEMA = "pulse-f0/1" EDGE_RE = re.compile(r"^(\w+) edge-filled.*front=([\d.]+)s, back=([\d.]+)s") # --------------------------------------------------------------------------- # signal processing (as in the original analysis, parameters from the config) # --------------------------------------------------------------------------- def emg_envelope(emg: np.ndarray, window: int) -> np.ndarray: rect = np.abs(emg - emg.mean(axis=0)) k = np.ones(window) / window env = np.stack([np.convolve(rect[:, c], k, mode="same") for c in range(rect.shape[1])], 1) tot = env.sum(axis=1) lo, hi = tot.min(), tot.max() return (tot - lo) / (hi - lo + 1e-8) if hi > lo else tot def fill_gaps(pos: np.ndarray, gap: np.ndarray, rid: str = "") -> np.ndarray: """Linear interpolation of each coordinate over the frames flagged in ``gap``.""" out = np.array(pos, dtype=np.float64) if gap.any(): good, bad = np.where(~gap)[0], np.where(gap)[0] if len(good) < 2: raise DataQualityError(f"{rid}: hand position is untracked in almost every frame", "mocap_untracked") for k in range(out.shape[1]): out[bad, k] = np.interp(bad, good, out[good, k]) return out def speed(pos: np.ndarray, window: int) -> np.ndarray: v = np.zeros_like(pos) v[1:] = pos[1:] - pos[:-1] s = np.linalg.norm(v, axis=1) return np.convolve(s, np.ones(window) / window, mode="same") def detect_onsets(p: np.ndarray, threshold: float, min_duration: int, min_gap: int, persist_frac: float, release_window: int, release_frac: float) -> List[int]: above = p > threshold onsets: List[int] = [] state = False n = len(above) for i in range(n): a = above[i] if a and not state: if i + min_duration < n and above[i:i + min_duration].mean() > persist_frac: if not onsets or i - onsets[-1] > min_gap: onsets.append(i) state = True elif not a and state: if i + release_window < n and above[i:i + release_window].mean() < release_frac: state = False return onsets def signal_onset(sig: np.ndarray, ref: int, window: int, threshold_ratio: float, baseline_frac: float, baseline_percentile: float) -> Optional[int]: start = max(0, ref - window) seg = sig[start:ref + 1] if len(seg) < 10: return None early = seg[:max(10, int(len(seg) * baseline_frac))] base = np.percentile(early, baseline_percentile) peak = seg.max() if peak - base < 1e-4: return None above = seg > base + (peak - base) * threshold_ratio if not above[-1]: rising = np.where(np.diff(above.astype(int)) == 1)[0] if len(rising) == 0: return None loc = rising[-1] + 1 else: loc = len(seg) - 1 while loc > 0 and above[loc - 1]: loc -= 1 return start + loc - ref def is_clean(env: np.ndarray, vel: np.ndarray, onset: int, look_back: int, rest_window: int, min_rel_increase: float) -> bool: r0, r1 = onset - look_back, onset - (look_back - rest_window) if r0 < 0: return False e_pre, v_pre = env[r1:onset], vel[r1:onset] if len(e_pre) < 10: return False e_dyn, v_dyn = env.max() - env.min(), vel.max() - vel.min() if e_dyn < 1e-6 or v_dyn < 1e-6: return False de = np.percentile(e_pre, 75) - env[r0:r1].mean() dv = np.percentile(v_pre, 75) - vel[r0:r1].mean() return bool(de / e_dyn > min_rel_increase and dv / v_dyn > min_rel_increase) # --------------------------------------------------------------------------- # one recording # --------------------------------------------------------------------------- HAND_SEGMENT = {"right": "RightHand", "left": "LeftHand"} HAND_CELLS = {"right": slice(0, 25), "left": slice(25, 50)} # PRESSURE_COLS: R1..R25, L1..L25 def edge_filled(meta: dict) -> Dict[str, tuple]: out = {} for w in meta.get("warnings", []) or []: m = EDGE_RE.match(str(w)) if m: out[m.group(1)] = (float(m.group(2)), float(m.group(3))) return out def place(data: np.ndarray, mod: str, span: dict, rid: str) -> np.ndarray: """Cut a stream to the common span of the alignment timeline (see ``span_of``).""" if data.shape[0] != span["lengths"][mod]: raise DataQualityError(f"{rid}: {mod} has {data.shape[0]} rows, the availability table " f"says {span['lengths'][mod]}", "rows") a = span["start"] - span["offsets"][mod] return data[a:a + span["n"]] def span_of(av: Availability, dr: DataRoot, rid: str) -> dict: """Placement of EMG, pressure and skeleton MoCap on the alignment timeline. Shared rule (``pulse.tasks.t2_data.recording_timeline``): a stream with the timeline's length starts at frame 0; the re-trimmed EMG / pressure files of v2s6, v13s2 and v13s3 start at the release offset. The analysis uses the frames covered by all three streams. """ from .t2_data import recording_timeline tl = recording_timeline(av, dr, rid, 1, modalities=SPAN_MODALITIES) return {"start": int(tl.start), "n": int(tl.n_frames_ds), "n_total": int(tl.n_total), "offsets": dict(tl.offsets), "lengths": dict(tl.lengths)} SPAN_MODALITIES = ("emg", "pressure", "mocap") def analyse_recording(job) -> dict: root, rid, cfg, span = job dr = DataRoot(root=Path(root)) pres = place(modality_from_stream(load_stream(dr, rid, "pressure"), "pressure").data, "pressure", span, rid).astype(np.float64) emg = place(modality_from_stream(load_stream(dr, rid, "emg"), "emg").data, "emg", span, rid).astype(np.float64) sk = load_stream(dr, rid, "mocap_skeleton") sk_values = place(sk.values, "mocap", span, rid) meta = load_alignment_metadata(dr, rid) T = span["n"] env = emg_envelope(emg, int(cfg["emg_envelope"]["window"])) ctx, post = int(round(cfg["context_sec"] * SR)), int(round(cfg["post_sec"] * SR)) fills = edge_filled(meta) blocked = np.zeros(T, dtype=bool) if cfg.get("exclude_edge_filled", True): for mod in ("mocap", "mocap_sq", "emg", "pressure"): if mod in fills: # edge-filled frames of the alignment timeline f, b = fills[mod] lo = int(math.ceil(f * SR)) - span["start"] hi = span["n_total"] - int(math.ceil(b * SR)) - span["start"] blocked[:max(0, lo)] = True blocked[max(0, hi):] = True d, o, c = cfg["detect"], cfg["onset"], cfg["clean"] lo_ms, hi_ms = cfg["delay_range_ms"] counts = {"onsets": 0, "no_context": 0, "edge_filled": 0, "mocap_gap": 0, "not_clean": 0, "no_onset": 0, "out_of_range": 0, "used": 0} events, traces = [], [] for hand in cfg["hands"]: col_idx = {n: i for i, n in enumerate(sk.columns)} seg = HAND_SEGMENT[hand] need = [f"{seg}_{a}" for a in "XYZ"] if any(n not in col_idx for n in need): raise ModalityUnavailableError(f"{rid}: skeleton TSV lacks {need}", "mocap_no_hand") raw = sk_values[:, [col_idx[n] for n in need]] # untracked hand frames (non-finite or exactly 0,0,0): linearly interpolated, # so the speed has no jump to the origin (which would also inflate the # recording's speed range used by the clean rule); events whose window # touches one are not used gap = ~np.isfinite(raw).all(axis=1) | (raw == 0).all(axis=1) pos = fill_gaps(raw, gap, rid) vel = speed(pos, int(cfg["velocity"]["smooth_window"])) p = pres[:, HAND_CELLS[hand]].sum(axis=1) for on in detect_onsets(p, float(cfg["pressure_threshold_g"]), int(d["min_duration"]), int(d["min_gap"]), float(d["persist_frac"]), int(d["release_window"]), float(d["release_frac"])): counts["onsets"] += 1 if on < ctx or on + post > T: counts["no_context"] += 1 continue if blocked[on - ctx:on + post].any(): counts["edge_filled"] += 1 continue if gap[on - ctx:on + post].any(): counts["mocap_gap"] += 1 continue if not is_clean(env, vel, on, int(c["look_back"]), int(c["rest_window"]), float(c["min_rel_increase"])): counts["not_clean"] += 1 continue args = (ctx, float(o["threshold_ratio"]), float(o["baseline_frac"]), float(o["baseline_percentile"])) de, dm = signal_onset(env, on, *args), signal_onset(vel, on, *args) if de is None or dm is None: counts["no_onset"] += 1 continue de_ms, dm_ms = de * 1000 / SR, dm * 1000 / SR if not (lo_ms <= de_ms <= hi_ms and lo_ms <= dm_ms <= hi_ms): counts["out_of_range"] += 1 continue counts["used"] += 1 events.append({"rid": rid, "volunteer": split_rid(rid)[0], "hand": hand, "onset_frame": int(span["start"] + on), # alignment timeline "onset_sec": (span["start"] + on) / SR, "emg_delay_ms": de_ms, "motion_delay_ms": dm_ms}) traces.append(np.stack([p[on - ctx:on + post], env[on - ctx:on + post], vel[on - ctx:on + post]]).astype(np.float32)) return {"rid": rid, "n_frames": int(T), "counts": counts, "events": events, "traces": traces, "edge_filled": fills, "span": span} # --------------------------------------------------------------------------- # statistics # --------------------------------------------------------------------------- def describe(x: np.ndarray) -> dict: q1, med, q3 = np.percentile(x, [25, 50, 75]) return {"n": int(len(x)), "mean": float(x.mean()), "sd": float(x.std(ddof=1)) if len(x) > 1 else None, "median": float(med), "p25": float(q1), "p75": float(q3), "iqr": float(q3 - q1), "min": float(x.min()), "max": float(x.max())} def paired_stats(emg: np.ndarray, motion: np.ndarray, vols: Sequence[str], n_boot: int, seed: int) -> dict: from scipy import stats as sps d = motion - emg n = len(d) se = d.std(ddof=1) / math.sqrt(n) tcrit = sps.t.ppf(0.975, n - 1) t = sps.ttest_rel(motion, emg) w = sps.wilcoxon(motion, emg) ev = {"n": n, "mean_diff_ms": float(d.mean()), "sd_ms": float(d.std(ddof=1)), "median_diff_ms": float(np.median(d)), "ci95_mean_ms": [float(d.mean() - tcrit * se), float(d.mean() + tcrit * se)], "paired_t": {"t": float(t.statistic), "df": n - 1, "p": float(t.pvalue)}, "wilcoxon": {"W": float(w.statistic), "p": float(w.pvalue)}, "motion_first_fraction": float(np.mean(d < 0)), "emg_first_fraction": float(np.mean(d > 0)), "tie_fraction": float(np.mean(d == 0)), "pearson_r_emg_motion": (float(np.corrcoef(emg, motion)[0, 1]) if emg.std() > 0 and motion.std() > 0 else None)} vols = np.asarray(vols) uv = sorted(set(vols), key=lambda v: int(v[1:])) per = {v: {"n_events": int((vols == v).sum()), "median_emg_ms": float(np.median(emg[vols == v])), "median_motion_ms": float(np.median(motion[vols == v])), "median_diff_ms": float(np.median(d[vols == v])), "mean_diff_ms": float(d[vols == v].mean())} for v in uv} md = np.array([per[v]["median_diff_ms"] for v in uv]) mm = np.array([per[v]["mean_diff_ms"] for v in uv]) vl = {"n_volunteers": len(uv), "median_of_volunteer_median_diffs_ms": float(np.median(md)), "mean_of_volunteer_mean_diffs_ms": float(mm.mean())} if len(uv) >= 2: vl["wilcoxon_volunteer_median_diffs"] = _wilcoxon(md) tt = sps.ttest_1samp(mm, 0.0) vl["t_volunteer_mean_diffs"] = {"t": float(tt.statistic), "df": len(uv) - 1, "p": float(tt.pvalue)} # Volunteer-level bootstrap (resample volunteers with replacement). Each CI # belongs to the point estimate stored next to it: the median of the # per-volunteer median differences, and the pooled event-level median # difference with volunteers as clusters. rng = np.random.default_rng(seed) idx = {v: np.where(vols == v)[0] for v in uv} b_vol, b_pool = np.empty(n_boot), np.empty(n_boot) for b in range(n_boot): pick = rng.integers(0, len(uv), len(uv)) b_vol[b] = np.median(md[pick]) b_pool[b] = np.median(np.concatenate([d[idx[uv[k]]] for k in pick])) vl["bootstrap_median_of_volunteer_medians_ci95_ms"] = [float(np.percentile(b_vol, 2.5)), float(np.percentile(b_vol, 97.5))] vl["pooled_median_diff_ms"] = float(np.median(d)) vl["cluster_bootstrap_pooled_median_diff_ci95_ms"] = [float(np.percentile(b_pool, 2.5)), float(np.percentile(b_pool, 97.5))] vl["n_bootstrap"] = int(n_boot) return {"event_level": ev, "volunteer_level": vl, "per_volunteer": per} def _wilcoxon(x: np.ndarray) -> dict: from scipy import stats as sps if np.all(x == 0): return {"W": 0.0, "p": 1.0} w = sps.wilcoxon(x) return {"W": float(w.statistic), "p": float(w.pvalue)} # --------------------------------------------------------------------------- # main # --------------------------------------------------------------------------- def main(argv=None) -> int: ap = argparse.ArgumentParser(prog="python -m pulse.tasks.f0", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) ap.add_argument("--root", default=None, help="dataset root (default $PULSE_ROOT)") ap.add_argument("--config", default=str(REPO_ROOT / "configs" / "f0" / "grasp_timing.yaml")) ap.add_argument("--set", action="append", default=[], metavar="KEY=VALUE") ap.add_argument("--out", default=str(REPO_ROOT / "runs" / "f0")) ap.add_argument("--availability", default=None) ap.add_argument("--workers", type=int, default=int(os.environ.get("SLURM_CPUS_PER_TASK", 4))) ap.add_argument("--print-manifest", action="store_true") args = ap.parse_args(argv) t0 = time.time() started = now() git_start = git_state() cfg = load_config(args.config, args.set) if cfg.get("task") != "f0": raise ValueError(f"{args.config} is not an F0 config") dr = DataRoot.from_arg(args.root) av = Availability.load(args.availability or default_availability_path(REPO_ROOT)) if av.data_tag != DATA_TAG or av.errors(): raise ProvenanceError("availability table is not a clean table for this data tag") vols = cfg.get("volunteers") or sorted({d["volunteer"] for d in av.table["recordings"].values()}, key=lambda v: int(v[1:])) pseudo = FoldSplit(pool="all", fold=0, train=(), inner_val=(), test=tuple(vols)) man = expected_manifest(av, pseudo, list(cfg["modalities"]), scenarios=tuple(cfg.get("scenarios") or SCENARIOS_TASK)) rids = man.partitions["test"] print(f"[manifest] {len(rids)} recordings from " f"{len({split_rid(r)[0] for r in rids})} volunteers ({man.md5[:8]})", flush=True) if args.print_manifest: print(json.dumps(man.to_dict(), indent=1)) return 0 jobs = [(str(dr.root), r, cfg, span_of(av, dr, r)) for r in rids] if args.workers > 1: with ProcessPoolExecutor(max_workers=args.workers) as ex: res = list(ex.map(analyse_recording, jobs, chunksize=1)) else: res = [analyse_recording(j) for j in jobs] verify_loaded(man, {"train": [], "inner_val": [], "test": [r["rid"] for r in res]}) events = [e for r in res for e in r["events"]] traces = [t for r in res for t in r["traces"]] if len(events) < 3: raise ValueError(f"only {len(events)} usable events") counts = {k: int(sum(r["counts"][k] for r in res)) for k in res[0]["counts"]} emg = np.array([e["emg_delay_ms"] for e in events]) mot = np.array([e["motion_delay_ms"] for e in events]) ev_vols = [e["volunteer"] for e in events] stats = {"emg_delay_ms": describe(emg), "motion_delay_ms": describe(mot), "paired_motion_minus_emg": paired_stats(emg, mot, ev_vols, int(cfg.get("n_bootstrap", 10000)), int(cfg.get("bootstrap_seed", 0)))} git_end = git_state() if git_end != git_start: raise ProvenanceError("the repository changed while the analysis was running; the recorded " "commit would not be the code that ran") out = Path(args.out) out.mkdir(parents=True, exist_ok=True) payload = { "schema": SCHEMA, "task": "f0", "counts": {**counts, "recordings": len(res), "recordings_with_events": len({e["rid"] for e in events}), "volunteers": len({split_rid(r["rid"])[0] for r in res}), "volunteers_with_events": len(set(ev_vols))}, "stats": stats, "caveats": ["EMG stream start times in alignment_metadata.json have whole-second " "resolution; absolute EMG onset times inherit that alignment uncertainty."], "edge_filled_recordings": {r["rid"]: r["edge_filled"] for r in res if r["edge_filled"]}, "placed_streams": {r["rid"]: {"span_start": r["span"]["start"], "span_frames": r["span"]["n"], "offsets": r["span"]["offsets"], "lengths": r["span"]["lengths"]} for r in res if any(r["span"]["offsets"].values()) or r["span"]["n"] < r["span"]["n_total"]}, "per_recording_counts": {r["rid"]: r["counts"] for r in res}, "provenance": { **git_end, "code_version": __version__, "data_tag": DATA_TAG, "availability_md5": av.md5, "manifest_md5": man.md5, "loaded_recordings": rids, "excluded_recordings": man.excluded["test"], "config_file": relpath_or_name(args.config), "config": cfg, "config_md5": json_md5(cfg), "overrides": list(args.set), "workers": args.workers, "python": sys.version.split()[0], "numpy": np.__version__, "started_at": started, "finished_at": now(), "slurm_job_id": os.environ.get("SLURM_JOB_ID")}, } with open(out / "f0_timing.json", "w", encoding="utf-8", newline="\n") as f: json.dump(payload, f, indent=1) f.write("\n") with open(out / "f0_events.csv", "w", encoding="utf-8", newline="") as f: w = csv.DictWriter(f, fieldnames=list(events[0]), lineterminator="\n") w.writeheader() w.writerows(events) ctx = int(round(cfg["context_sec"] * SR)) np.savez_compressed(out / "f0_traces.npz", traces=np.stack(traces), channels=np.array(["pressure_g", "emg_envelope", "hand_speed"]), time_ms=(np.arange(traces[0].shape[1]) - ctx) * 1000.0 / SR, rid=np.array([e["rid"] for e in events])) pe = stats["paired_motion_minus_emg"]["event_level"] print(f"[f0] {counts['used']} events ({payload['counts']['recordings_with_events']} recordings, " f"{payload['counts']['volunteers_with_events']} volunteers) of {counts['onsets']} contact " f"onsets; EMG median {stats['emg_delay_ms']['median']:.0f} ms (IQR " f"{stats['emg_delay_ms']['iqr']:.0f}), motion median {stats['motion_delay_ms']['median']:.0f} ms " f"(IQR {stats['motion_delay_ms']['iqr']:.0f}); motion-EMG mean {pe['mean_diff_ms']:.1f} ms, " f"paired t p={pe['paired_t']['p']:.3g}, Wilcoxon p={pe['wilcoxon']['p']:.3g} " f"({time.time() - t0:.0f}s)", flush=True) print(f"[f0] wrote {out / 'f0_timing.json'}", flush=True) return 0 if __name__ == "__main__": sys.exit(main())