velvet-pine-22's picture
PULSE-code: benchmark code for the PULSE dataset (camera-ready release)
dffbc1f verified
Raw History Blame Contribute Delete
24.6 kB
"""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())