PULSE-code / figures /f0 /plot_f0.py
velvet-pine-22's picture
PULSE-code: benchmark code for the PULSE dataset (camera-ready release)
dffbc1f verified
Raw History Blame Contribute Delete
9.08 kB
#!/usr/bin/env python
"""F0 figures and number macros from ``python -m pulse.tasks.f0`` output.
python figures/f0/plot_f0.py --in runs/f0 --out figures/out --tables tables
Writes ``f0_grasp_phase_timing.{pdf,png}`` (event-aligned, per-event min-max
scaled pressure / EMG envelope / hand speed, mean +- 0.5 SD, median onsets),
``f0_delay_distributions.{pdf,png}`` (EMG onset, motion onset, paired
motion - EMG difference) and ``<tables>/numbers_f0.tex``
(``\\pulsenum{f0/emg/median}`` etc.).
"""
from __future__ import annotations
import argparse
import json
import sys
from pathlib import Path
import numpy as np
REPO = Path(__file__).resolve().parents[2]
sys.path.insert(0, str(REPO))
import matplotlib # noqa: E402
matplotlib.use("Agg")
import matplotlib.pyplot as plt # noqa: E402
# reference palette (categorical slots 1-3 validate all-pairs) and ink tokens
SERIES = {"emg": "#2a78d6", "motion": "#eb6834", "pressure": "#1baf7a"}
INK, INK2, MUTED, GRID, AXIS, SURFACE = "#0b0b0b", "#52514e", "#898781", "#e1e0d9", "#c3c2b7", "#fcfcfb"
def style():
plt.rcParams.update({
"pdf.fonttype": 42, "ps.fonttype": 42, "font.size": 9, "axes.titlesize": 9,
"axes.labelsize": 9, "legend.fontsize": 8, "xtick.labelsize": 8, "ytick.labelsize": 8,
"axes.edgecolor": AXIS, "axes.labelcolor": INK2, "xtick.color": MUTED, "ytick.color": MUTED,
"text.color": INK, "axes.grid": True, "grid.color": GRID, "grid.linewidth": 0.6,
"grid.linestyle": "-", "axes.spines.top": False, "axes.spines.right": False,
"figure.facecolor": "white", "axes.facecolor": "white", "savefig.facecolor": "white",
"legend.frameon": False,
})
def minmax(a):
a = a - a.min(axis=1, keepdims=True)
return a / (a.max(axis=1, keepdims=True) + 1e-8)
def phase_figure(res, z, out: Path):
tr, t = z["traces"], z["time_ms"]
st = res["stats"]
fig, ax = plt.subplots(figsize=(5.2, 2.9))
ax.axvline(0, color=INK2, lw=0.8)
ax.text(8, 1.07, "contact", color=INK2, fontsize=8, va="bottom")
for ch, key, label in ((1, "emg", "EMG envelope"), (2, "motion", "Hand speed"),
(0, "pressure", "Contact pressure")):
a = minmax(tr[:, ch, :].astype(np.float64))
m, s = a.mean(0), a.std(0)
ax.fill_between(t, m - 0.5 * s, m + 0.5 * s, color=SERIES[key], alpha=0.12, lw=0)
ax.plot(t, m, color=SERIES[key], lw=1.6, label=label, solid_capstyle="round")
meds = {k: st[f"{k}_delay_ms"]["median"] for k in ("emg", "motion")}
later = max(meds, key=meds.get)
for key, y in (("emg", 0.93), ("motion", 0.93)):
med = meds[key]
ax.plot([med, med], [0, y], color=SERIES[key], lw=1.0)
ax.plot([med], [y], "o", ms=4, color=SERIES[key], mec="white", mew=1.0)
right = key == later # later onset labelled to the right, earlier to the left
ax.text(med + (12 if right else -12), y, f"{'EMG' if key == 'emg' else 'motion'} onset\n"
f"median {med:.0f} ms", ha="left" if right else "right", va="center",
fontsize=7, color=INK)
c = res["counts"]
ax.set_title(f"Right-hand contacts: {c['used']} events, {c['recordings_with_events']} recordings, "
f"{c['volunteers_with_events']} volunteers", loc="left", color=INK)
ax.set_xlabel("time relative to contact onset (ms)")
ax.set_ylabel("scaled amplitude")
ax.set_xlim(t[0], t[-1])
ax.set_ylim(-0.05, 1.18)
ax.legend(loc="upper left", bbox_to_anchor=(0.0, 0.93), handlelength=1.6)
fig.tight_layout()
for ext in ("pdf", "png"):
fig.savefig(out / f"f0_grasp_phase_timing.{ext}", dpi=200)
plt.close(fig)
def delay_figure(res, events_ms, out: Path):
emg, mot = events_ms
d = mot - emg
st = res["stats"]
pe = st["paired_motion_minus_emg"]["event_level"]
fig, axes = plt.subplots(1, 3, figsize=(7.4, 2.5), sharey=False)
bins = np.arange(-1500, 1, 50)
for ax, x, key, title in ((axes[0], emg, "emg", "EMG onset"), (axes[1], mot, "motion", "Motion onset")):
s = st[f"{key}_delay_ms"]
ax.hist(x, bins=bins, color=SERIES[key], edgecolor="white", linewidth=0.6)
ax.axvline(s["median"], color=INK, lw=1.0)
ax.set_title(f"{title}\nmedian {s['median']:.0f} ms, IQR {s['iqr']:.0f} ms", loc="left")
ax.set_xlabel("ms relative to contact")
lim = max(50, float(np.percentile(np.abs(d), 99)))
b = np.arange(-np.ceil(lim / 50) * 50, np.ceil(lim / 50) * 50 + 1, 50)
axes[2].hist(d, bins=b, color=INK2, edgecolor="white", linewidth=0.6)
axes[2].axvline(0, color=AXIS, lw=1.0)
axes[2].axvline(pe["median_diff_ms"], color=INK, lw=1.0)
axes[2].set_title(f"Motion - EMG (paired)\n"
f"median {pe['median_diff_ms']:.0f} ms, p = {pe['wilcoxon']['p']:.2g}", loc="left")
axes[2].set_xlabel("ms (negative: motion first)")
axes[0].set_ylabel("events")
fig.tight_layout()
for ext in ("pdf", "png"):
fig.savefig(out / f"f0_delay_distributions.{ext}", dpi=200)
plt.close(fig)
def numbers(res) -> dict:
st, c = res["stats"], res["counts"]
pm = st["paired_motion_minus_emg"]
ev, vl = pm["event_level"], pm["volunteer_level"]
n = {"f0/events": str(c["used"]), "f0/onsets": str(c["onsets"]),
"f0/recordings": str(c["recordings_with_events"]), "f0/recordingsscanned": str(c["recordings"]),
"f0/volunteers": str(c["volunteers_with_events"])}
for key in ("emg", "motion"):
s = st[f"{key}_delay_ms"]
for k in ("mean", "sd", "median", "p25", "p75", "iqr"):
n[f"f0/{key}/{k}"] = f"{s[k]:.0f}"
n.update({"f0/diff/mean": f"{ev['mean_diff_ms']:.1f}", "f0/diff/median": f"{ev['median_diff_ms']:.0f}",
"f0/diff/sd": f"{ev['sd_ms']:.0f}",
"f0/diff/cilo": f"{ev['ci95_mean_ms'][0]:.0f}", "f0/diff/cihi": f"{ev['ci95_mean_ms'][1]:.0f}",
"f0/diff/pt": _p(ev["paired_t"]["p"]), "f0/diff/pw": _p(ev["wilcoxon"]["p"]),
"f0/diff/motionfirst": f"{100 * ev['motion_first_fraction']:.0f}",
"f0/diff/r": ("--" if ev["pearson_r_emg_motion"] is None
else f"{ev['pearson_r_emg_motion']:.2f}"),
"f0/vol/n": str(vl["n_volunteers"]),
"f0/vol/median": f"{vl['median_of_volunteer_median_diffs_ms']:.0f}"})
if "wilcoxon_volunteer_median_diffs" in vl:
n["f0/vol/pw"] = _p(vl["wilcoxon_volunteer_median_diffs"]["p"])
n["f0/vol/pt"] = _p(vl["t_volunteer_mean_diffs"]["p"])
# CI of f0/vol/median (median of the per-volunteer median differences)
lo, hi = vl["bootstrap_median_of_volunteer_medians_ci95_ms"]
n["f0/vol/cilo"], n["f0/vol/cihi"] = f"{lo:.0f}", f"{hi:.0f}"
# pooled event-level median difference (= f0/diff/median), volunteers as clusters
lo, hi = vl["cluster_bootstrap_pooled_median_diff_ci95_ms"]
n["f0/diff/medcilo"], n["f0/diff/medcihi"] = f"{lo:.0f}", f"{hi:.0f}"
return n
def _p(p):
from pulse.stats import format_p
return format_p(p)
def write_numbers(nums: dict, path: Path, res: dict):
from pulse.aggregate import NUMBERS_PREAMBLE
prov = res["provenance"]
lines = [NUMBERS_PREAMBLE, f"% ---- F0 case study (python -m pulse.tasks.f0): git {prov.get('git_sha')} "
f"data {prov.get('data_tag')} config md5 {prov.get('config_md5')}"]
for k, v in sorted(nums.items()):
lines.append(r"\expandafter\def\csname pulse@" + k + r"\endcsname{" + v + "}")
path.write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")
def main(argv=None) -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--in", dest="inp", default="runs/f0")
ap.add_argument("--out", default="figures/out")
ap.add_argument("--tables", default="tables")
args = ap.parse_args(argv)
inp, out, tab = Path(args.inp), Path(args.out), Path(args.tables)
out.mkdir(parents=True, exist_ok=True)
tab.mkdir(parents=True, exist_ok=True)
res = json.loads((inp / "f0_timing.json").read_text(encoding="utf-8"))
if res.get("schema") != "pulse-f0/1":
raise SystemExit(f"{inp / 'f0_timing.json'} is not an F0 result")
z = np.load(inp / "f0_traces.npz")
import csv
with open(inp / "f0_events.csv", encoding="utf-8") as f:
rows = list(csv.DictReader(f))
emg = np.array([float(r["emg_delay_ms"]) for r in rows])
mot = np.array([float(r["motion_delay_ms"]) for r in rows])
if len(rows) != res["counts"]["used"] or z["traces"].shape[0] != len(rows):
raise SystemExit("f0_events.csv / f0_traces.npz do not match f0_timing.json")
style()
phase_figure(res, z, out)
delay_figure(res, (emg, mot), out)
write_numbers(numbers(res), tab / "numbers_f0.tex", res)
print(f"wrote {out / 'f0_grasp_phase_timing.pdf'}, {out / 'f0_delay_distributions.pdf'}, "
f"{tab / 'numbers_f0.tex'}")
return 0
if __name__ == "__main__":
sys.exit(main())