Upload 22 files

.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.DS_Store
+Thumbs.db
+
+# Recordings stay local. Copy them into data/raw/ to train.
+data/raw/*
+!data/raw/.gitkeep
+!data/raw/README.md
+
+# Each train writes a folder here. The code is the repo; the weights are a run.
+runs/*
+!runs/.gitkeep

README.md

@@ -1,3 +1,258 @@
 ---
 license: mit
+library_name: pytorch
+tags:
+  - emg
+  - surface-emg
+  - gesture-recognition
+  - hand-pose
+  - wearable
+  - onnx
+  - pytorch
+  - pieeg
 ---
+
+# AuraNet: wrist EMG gesture recognition for Aura
+
+> **Status: architecture and training code only.** Trained weights (`model.onnx`, `model.pt`) are not published yet and will be added in a later version. Run `python train.py` to train your own.
+
+AuraNet is a small temporal-spatial CNN for the **Aura** 8-channel surface-EMG wristband by PiEEG ([aura.pieeg.com](https://aura.pieeg.com/)).
+
+| | |
+|---|---|
+| Input | `float32 [batch, 250, 8]` (1 s at 250 Hz, time then channel), filtered and scaled outside the graph |
+| Output | softmax over 6 classes: `rest`, `fist`, `open`, `pinch`, `point`, `thumb-up` |
+| Second head | 7-DoF hand pose in `[0, 1]` (`python train.py --pose`) |
+| Export | ONNX (opset 17) + PyTorch checkpoint |
+
+Built as the baseline for the **Aura: Calibration-Free EMG Challenge** on Kaggle: <https://www.kaggle.com/competitions/vr-calibration-free-emg-challenge-pieeg>
+
+---
+
+# Aura wrist EMG training pipeline example
+
+Baseline pipeline for the Aura hand-EMG Kaggle competition. Aura is an 8-channel surface-EMG wristband ([aura.pieeg.com](https://aura.pieeg.com/)). One session file in, one ONNX model out. Two targets from the same recordings.
+
+`Python 3.10+` · `250 Hz` · `8 ch` · `window 1.0 s` · `ONNX`
+
+| Target | Command | Graph | Output |
+| --- | --- | --- | --- |
+| Gesture, 6 class | `python train.py` | `model.onnx` | softmax: rest, fist, open, pinch, point, thumb-up |
+| Hand pose, 7 DoF | `python train.py --pose` | `pose.onnx` | `[0, 1]`: five finger curls, pinch, openness |
+
+This directory is the working tree. Run every command from here.
+
+> Filter, per-channel scale, and the 0.5 s warmup live **outside** the graph. Do not feed raw microvolts to ONNX. Copy `infer.py`.
+
+```mermaid
+flowchart LR
+  A["session .xlsx / .csv"] --> B["causal filter + scale"]
+  B --> C["1 s windows, hop 0.1 s"]
+  C --> D["AuraNet"]
+  D --> E["model.onnx"]
+  D --> F["pose.onnx"]
+```
+
+## Index
+
+| | Section | Contents |
+| --- | --- | --- |
+| ⚡ | [Quick start](#quick-start) | venv, first train |
+| ⌨️ | [Commands](#commands) | train, pose, loso, infer |
+| 📁 | [Data](#data) | columns, labels, pose targets |
+| ⚙️ | [Method](#method) | filter, windows, QC, AuraNet |
+| 🤚 | [Pose regression](#pose-regression) | 7-DoF optical target |
+| ✂️ | [Split](#split) | session-level, LOSO |
+| 💻 | [Hardware](#hardware) | CPU vs T4 |
+| 📦 | [Run artifacts](#run-artifacts) | `runs/<timestamp>/` |
+| 🔌 | [Inference contract](#inference-contract) | `model.onnx` I/O |
+| 📏 | [Pose inference contract](#pose-inference-contract) | `pose.onnx` I/O |
+| 🗂️ | [Layout](#layout) | files |
+| 🔧 | [Configuration](#configuration) | `config.yaml` |
+
+## Quick start
+
+Python 3.10+.
+
+```powershell
+py -3 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+```
+
+Put one file per session in `data/raw/` (`.xlsx` or `.csv`). Then:
+
+```powershell
+python train.py --qc-only
+python train.py
+python infer.py
+```
+
+Dependencies: NumPy, pandas, openpyxl, SciPy, PyYAML, PyTorch, ONNX, ONNX Runtime.
+
+`--qc-only` writes the channel table and does not train. `--self-test` trains for one epoch on synthetic tensors and checks that the ONNX file loads. It does not read `data/raw/`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `python train.py --qc-only` | Channel QC only. No fit. |
+| `python train.py` | 6-class classifier → `model.onnx` |
+| `python train.py --pose` | 7-DoF pose regressor → `pose.onnx` |
+| `python train.py --data D:\more-sessions` | Read sessions from another folder |
+| `python train.py --test multimodal_15` | Pin the test session |
+| `python train.py --loso` | Leave-one-session-out on train+val. Test stays sealed. Does not replace `model.onnx` |
+| `python train.py --self-test` | One synthetic epoch. No `data/raw/` |
+| `python infer.py` | One-window ONNX caller (latest `model.onnx`) |
+| `python infer.py runs\RUN\model.onnx` | Same, explicit graph |
+
+## Data
+
+Place one file per session in `data/raw/`. Accepted formats are `.xlsx` (first sheet) and `.csv`. Excel lock files (`~$*`) are ignored.
+
+| Column | Role |
+| --- | --- |
+| `t` | Time in seconds from session start |
+| `emg_new` | If present, only rows with value 1 are kept |
+| `ch1` … `ch8` | EMG in microvolts |
+| `label` | Class name |
+| `label_source` | If present, only `guided` rows are labeled. Other rows are unlabeled |
+| `optical_*` | Optical tracker metadata. Not a classifier input. See `drop_optical_disagreement` |
+| `thumb_curl` … `pinky_curl`, `pinch`, `openness` | Continuous pose in `[0, 1]`. The `--pose` target, not an input |
+
+IMU columns (`ax`, `ay`, `az`, `gx`, `gy`, `gz`, `roll`, `pitch`, `yaw`) are not read. Class names are normalized (`open hand` → `open`, `thumb up` → `thumb-up`). Anything outside the six-class list is unlabeled.
+
+Recordings are not part of the repository. `data/raw/` is gitignored except for its note.
+
+If `data/raw/` is empty, `fallback_data_dir` in `config.yaml` is used when that path exists.
+
+## Method
+
+Sampling rate is 250 Hz. Files more than 2% off that rate are resampled. The first 0.5 s after filtering is dropped as filter warmup.
+
+Preprocessing, applied before the network and not inside the ONNX graph:
+
+1. Causal bandpass 20–120 Hz, order 4.
+2. Causal bandstop 45–55 Hz, order 4.
+3. Causal notch at 100 Hz, Q = 30.
+4. Per-channel scale `median(|x|) / 0.6745`, with a floor of `1e-6`.
+
+Windows are 1.0 s (250 samples) with a hop of 0.1 s. Samples within 0.2 s of a label change are unlabeled, so ramp intervals are not used as holds. A window is kept when at least 90% of its samples share one class and no second class is present.
+
+Channel QC, per file, on the filtered signal:
+
+- Drop if the channel is empty, flat (std < 1 µV or peak-to-peak < 2 µV), railed, or listed in `drop_channels`.
+- Report SNR of active grips versus rest, and the fraction of 20–120 Hz power in the 49–51 Hz band. Low SNR is not an automatic drop.
+- A channel is zeroed in the shipped graph only if it hard-fails in at least `global_drop_fraction` of the train files, or it is listed in `drop_channels`. The mask is estimated from the train files only, so neither validation nor test decides which channels exist.
+
+The network is a temporal-spatial convolutional classifier (time convolution, depthwise mix across the 8 channels, separable convolution, linear head). Input layout is `(batch, time, channels)`. Output is a softmax over the six classes, index 0 = rest. Training uses class-weighted cross-entropy and AdamW. Early stopping watches validation balanced accuracy.
+
+## Pose regression
+
+`python train.py --pose` trains a continuous hand-pose regressor on the same recordings and the same windows. The target is the optical hand tracker carried in each session file: seven values in `[0, 1]`, the five per-finger curls plus pinch and openness. This is an optical estimate, not motion capture, so the model distils that tracker into EMG and its ceiling is the tracker's own quality.
+
+The target for a window is the confidence-weighted median pose over that window. A window is used when at least half its samples carry a present, valid pose and the median optical confidence clears `pose_min_conf`. Loss is Smooth L1 weighted by confidence, and early stopping watches validation mean absolute error. The network reuses the classifier backbone with a sigmoid head, so the output is a pose vector in `[0, 1]`. Reported metrics are per-DoF MAE and Pearson correlation on the test sessions.
+
+## Split
+
+The split unit is the session file. Windows from one file are not placed on both sides of a split: the hop is 100 ms inside a 1 s window, so neighboring windows are the same contraction.
+
+With the session lists in `config.yaml` empty, files are shuffled with `seed` and cut by `test_fraction` and `val_fraction` (default 20% test, 20% validation, remainder train). At least one file is required in each role, and at least three files are required in total.
+
+| Role | Use |
+| --- | --- |
+| Train | Weight updates |
+| Validation | Early stopping only |
+| Test | One score after training. Not in the loss, not in early stopping, not in the exported weights |
+
+`runs/<timestamp>/split.json` is the assignment from that run. Copy it into `train_sessions`, `val_sessions`, and `test_sessions` to freeze the split. Files that are not listed are appended to train.
+
+`--loso` runs leave-one-session-out on train and validation only. It does not score or modify the test files, and it does not replace `model.onnx`.
+
+The reported test metric is balanced accuracy. Rest is the majority class, so unweighted accuracy is not the selection metric.
+
+## Hardware
+
+AuraNet is a small temporal-spatial CNN (8 channels, 1 s window). One `python train.py` run is fine on CPU. `--loso` is 12 extra trains on the train+val sessions (test stays sealed), each for the shipped epoch count, so it is slow on CPU. The network is not large; a free T4 is enough.
+
+| Budget | Where | Notes |
+| --- | --- | --- |
+| $0 | Kaggle notebook, GPU on | ~30 GPU hours/week. Best free option for this competition. |
+| $0 | Colab, Runtime > GPU (T4 if assigned) | Works. GPU is not guaranteed. Idle disconnect. [notebooks/loso.ipynb](notebooks/loso.ipynb) |
+| $0 | This machine, CPU | Single train: yes. LOSO: hours. Do not start it here. |
+| ~$1 | Any rented T4 / RTX, SSH | One LOSO job. |
+
+Do not `pip install torch` on Colab or Kaggle. Those runtimes already ship CUDA PyTorch; a pip torch often replaces it with CPU. Install the rest from `requirements.txt`. Session files are ~104 MB and are not in git: put them in `data/raw/` (upload, Drive, or Kaggle dataset). `loso.json` is written after each fold so a dropped session still keeps completed scores.
+
+## Run artifacts
+
+Each training writes `runs/<timestamp>/`. `runs/latest.txt` stores that path.
+
+| File | Contents |
+| --- | --- |
+| `split.json` | Train, validation, and test session names |
+| `qc.md`, `qc.json` | Per-session channel std, SNR, mains ratio, keep/drop |
+| `report.md`, `report.json` | Train counts, validation score, test score, test confusion matrix |
+| `model.onnx` | Exported network. Weights from the train split only |
+| `model.pt` | PyTorch checkpoint, same weights, plus the split and channel mask |
+| `contract.json` | Inference contract below |
+| `pose.onnx` | Pose regressor. Present only after `--pose` |
+| `pose.pt` | Pose checkpoint, plus DoF names, split, and channel mask. `--pose` only |
+| `pose_contract.json`, `pose_report.md`, `pose_report.json` | Pose contract and scores. `--pose` only |
+| `loso.json` | Present only after `--loso` |
+
+## Inference contract
+
+`contract.json` is authoritative for a given run. Defaults:
+
+| Field | Value |
+| --- | --- |
+| Input name | `emg` |
+| Input | `float32`, `[batch, 250, 8]`, time then channel |
+| Output name | `probs` |
+| Output | `float32`, `[batch, 6]`, sums to 1 |
+| Class order | `rest`, `fist`, `open`, `pinch`, `point`, `thumb-up` |
+| Sample rate | 250 Hz |
+| Graph contents | Classifier only. Filter, scale, and warmup are the caller's responsibility |
+| Channel mask | Zeroed inside the graph. See `channel_keep` |
+
+```powershell
+python infer.py
+python infer.py runs\RUN\model.onnx
+```
+
+`infer.py` loads `model.onnx`, runs a mock 1 s buffer through the same causal filter and per-channel scale as training, and prints class probabilities. With no path it uses `runs/latest.txt` if that run has `model.onnx`, otherwise the newest `runs/*/model.onnx`.
+
+The mock buffer is synthetic EMG in microvolts. Scale is computed on that 1 s window; training uses the full recording. A live caller should keep SOS filter state across hops instead of re-applying the 0.5 s warmup every window.
+
+## Pose inference contract
+
+`pose_contract.json` is authoritative for a `--pose` run. Defaults:
+
+| Field | Value |
+| --- | --- |
+| Input | `float32`, `[batch, 250, 8]`, time then channel |
+| Output name | `pose` |
+| Output | `float32`, `[batch, 7]`, each value in `[0, 1]` |
+| DoF order | `thumb_curl`, `index_curl`, `middle_curl`, `ring_curl`, `pinky_curl`, `pinch`, `openness` |
+| Target source | Optical hand tracker, not motion capture |
+| Preprocess | Same causal filter and per-channel scale as the classifier, applied by the caller |
+
+## Layout
+
+```
+config.yaml          training and split configuration
+train.py             entry point
+infer.py             one-window ONNX caller (filter and scale outside the graph)
+aura_pipeline/       load, QC, windows, model, fit, export, pose
+data/raw/            session files
+runs/                outputs, gitignored
+```
+
+## Configuration
+
+All knobs are in `config.yaml`. Do not hard-code channels, epochs, or split lists in Python.
+
+`drop_optical_disagreement` defaults to false. Optical fields are last-value holds on the EMG time base, so a sample-level veto is not a reliable label. When enabled, a guided sample is unlabeled if `optical_present` is set, `optical_conf` is at least `optical_conf_min`, and `optical_class` names a different class. The pair rest/open is exempt.
+
+`pose_targets`, `pose_min_conf`, and `pose_loss_beta` configure the `--pose` regressor: the DoF columns to predict, the median-confidence floor for keeping a window, and the Smooth L1 transition point.

aura_pipeline/__init__.py

@@ -0,0 +1,3 @@
+"""Training package for 8-channel hand EMG."""
+
+__version__ = "1.0.0"

aura_pipeline/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aura_pipeline/cli.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+import argparse
+import json
+import warnings
+from datetime import datetime
+from pathlib import Path
+
+import numpy as np
+import torch
+
+from .config import ROOT, load_config, resolve_dir
+from .data import apply_mask, discover, global_mask, load_session, make_windows
+from .export import export_onnx, write_contract
+from .fit import (
+    balanced_accuracy,
+    confusion,
+    predict,
+    session_sample_weights,
+    set_seed,
+    train_model,
+)
+from .report import write_qc, write_report
+from .split import assign_sessions
+
+warnings.filterwarnings("ignore", message="Workbook contains no default style")
+
+
+def _parse(argv: list[str] | None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Train the Aura hand model and write ONNX.")
+    p.add_argument("--config", type=Path, default=None)
+    p.add_argument("--data", type=Path, default=None, help="Folder of xlsx/csv sessions.")
+    p.add_argument("--qc-only", action="store_true", help="Channel report only. No training.")
+    p.add_argument("--self-test", action="store_true", help="Train on synthetic EMG and export ONNX.")
+    p.add_argument("--loso", action="store_true", help="Also score leave-one-session-out. Slow.")
+    p.add_argument("--pose", action="store_true", help="Train continuous hand-pose regression, not the classifier.")
+    p.add_argument("--epochs", type=int, default=None)
+    p.add_argument("--window-sec", type=float, default=None, help="Override config window_sec for this run.")
+    p.add_argument(
+        "--session-balanced",
+        action="store_true",
+        help="Draw train windows so each session has equal mass. Classifier only.",
+    )
+    p.add_argument("--test", action="append", default=None, help="Pin a session into the test split. Repeatable.")
+    return p.parse_args(argv)
+
+
+def _data_dir(cfg: dict, override: Path | None) -> Path:
+    if override is not None:
+        path = override if override.is_absolute() else (Path.cwd() / override)
+        path = path.resolve()
+        if not discover(path):
+            raise SystemExit(f"No xlsx or csv in {path}")
+        return path
+    primary = resolve_dir(ROOT, cfg["data_dir"])
+    if primary and discover(primary):
+        return primary
+    fallback = resolve_dir(ROOT, cfg.get("fallback_data_dir"))
+    if fallback and discover(fallback):
+        print(f"data/raw is empty. Using {fallback}")
+        return fallback
+    raise SystemExit(
+        "No recordings found. Put session xlsx or csv files in data/raw, or pass --data <folder>."
+    )
+
+
+def _run_dir() -> Path:
+    path = ROOT / "runs" / datetime.now().strftime("%Y%m%d_%H%M%S")
+    path.mkdir(parents=True, exist_ok=True)
+    (ROOT / "runs" / "latest.txt").write_text(str(path), encoding="utf-8")
+    return path
+
+
+def _bundle(cfg: dict, folder: Path):
+    files = discover(folder)
+    print(f"{len(files)} session file(s) in {folder}", flush=True)
+    sessions = []
+    for path in files:
+        print(f"  load {path.name}", flush=True)
+        sessions.append(load_session(path, cfg))
+    return sessions
+
+
+def _windows_by_session(sessions, cfg, mask):
+    xs, ys, names = [], [], []
+    for session in sessions:
+        x, y = make_windows(session, cfg)
+        x = apply_mask(x, mask)
+        if len(x) == 0:
+            print(f"  no clean windows in {session.name}", flush=True)
+            continue
+        print(f"  {session.name}: {len(x)} windows", flush=True)
+        xs.append(x)
+        ys.append(y)
+        names.append(session.name)
+    return xs, ys, names
+
+
+def _concat(xs, ys):
+    if not xs:
+        win = 250
+        return np.empty((0, win, 8), np.float32), np.empty((0,), np.int64)
+    return np.concatenate(xs), np.concatenate(ys)
+
+
+def _check_classes(y: np.ndarray, classes: list[str]) -> None:
+    missing = [name for i, name in enumerate(classes) if np.sum(y == i) == 0]
+    if missing:
+        raise SystemExit(
+            "No windows for: " + ", ".join(missing) + ". Check guided labels before training."
+        )
+
+
+def run_self_test() -> int:
+    from .model import AuraNet
+
+    cfg = load_config()
+    cfg["epochs"] = 1
+    cfg["patience"] = 1
+    cfg["batch_size"] = 16
+    fs = 250
+    win = 250
+    rng = np.random.default_rng(0)
+    xs, ys = [], []
+    for cls in range(len(cfg["classes"])):
+        block = rng.normal(0, 0.2, size=(24, win, 8)).astype(np.float32)
+        block[:, :, cls % 8] += 1.5 + 0.3 * cls
+        xs.append(block)
+        ys.append(np.full(len(block), cls, np.int64))
+    x = np.concatenate(xs)
+    y = np.concatenate(ys)
+    mask = [True] * 8
+    mask[7] = False
+    x[:, :, 7] = 0.0
+    set_seed(int(cfg["seed"]))
+    model, info = train_model(x, y, x[:32], y[:32], cfg, mask, epochs=1)
+    out = _run_dir()
+    onnx_path = out / "model.onnx"
+    export_onnx(model, onnx_path, cfg["classes"])
+    write_contract(out / "contract.json", cfg, mask, {"train": ["synthetic"], "val": [], "test": []})
+    probe = AuraNet(channel_mask=mask)
+    probe.load_state_dict(model.cpu().state_dict())
+    print(f"self-test ok  device={info['device']}  onnx={onnx_path}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse(argv)
+    if args.self_test:
+        return run_self_test()
+
+    cfg = load_config(args.config)
+    if args.epochs is not None:
+        cfg["epochs"] = args.epochs
+    if args.window_sec is not None:
+        cfg["window_sec"] = float(args.window_sec)
+    if args.session_balanced:
+        cfg["session_balanced"] = True
+    if args.loso:
+        cfg["loso"] = True
+    if args.test:
+        cfg["test_sessions"] = list(args.test)
+
+    folder = _data_dir(cfg, args.data)
+    sessions = _bundle(cfg, folder)
+    mask = global_mask(sessions, cfg)
+    out = _run_dir()
+    rows = [row for s in sessions for row in s.qc_rows]
+    write_qc(out / "qc.md", rows, mask)
+    (out / "qc.json").write_text(json.dumps({"mask": mask, "rows": rows}, indent=2), encoding="utf-8")
+    print("channel keep: " + " ".join(f"ch{i+1}" for i, k in enumerate(mask) if k), flush=True)
+    print(f"qc report: {out / 'qc.md'}", flush=True)
+    if args.qc_only:
+        return 0
+
+    by_name = {s.name: s for s in sessions if s.name}
+    split = assign_sessions([s.name for s in sessions], cfg)
+    # Channel mask is fit on train only. Validation and test must not decide which channels exist.
+    mask = global_mask([by_name[n] for n in split["train"] if n in by_name], cfg)
+    write_qc(out / "qc.md", rows, mask)
+    (out / "qc.json").write_text(json.dumps({"mask": mask, "rows": rows, "split": split}, indent=2), encoding="utf-8")
+    print("channel keep: " + " ".join(f"ch{i+1}" for i, k in enumerate(mask) if k), flush=True)
+    print(
+        "split  train={train}  val={val}  test={test}".format(**{k: ",".join(v) for k, v in split.items()}),
+        flush=True,
+    )
+    (out / "split.json").write_text(json.dumps(split, indent=2), encoding="utf-8")
+
+    if args.pose:
+        from .pose import run_pose
+
+        return run_pose(sessions, cfg, out, split, mask)
+
+    xs, ys, names = _windows_by_session(sessions, cfg, mask)
+    if not names:
+        raise SystemExit("No trainable windows. See the QC report.")
+    have = set(names)
+    for role, group in split.items():
+        missing = [n for n in group if n not in have]
+        if missing:
+            raise SystemExit(f"{role} sessions have no clean windows: {', '.join(missing)}")
+    groups = {}
+    for role in ("train", "val", "test"):
+        chosen = [names.index(n) for n in split[role]]
+        groups[role] = _concat([xs[i] for i in chosen], [ys[i] for i in chosen])
+    x_tr, y_tr = groups["train"]
+    x_val, y_val = groups["val"]
+    x_te, y_te = groups["test"]
+    _check_classes(y_tr, cfg["classes"])
+    counts = {name: int(np.sum(y_tr == i)) for i, name in enumerate(cfg["classes"])}
+    print("train windows " + ", ".join(f"{k}={v}" for k, v in counts.items()), flush=True)
+    sample_weights = None
+    if cfg.get("session_balanced"):
+        train_lengths = [len(ys[i]) for i in [names.index(n) for n in split["train"]]]
+        sample_weights = session_sample_weights(train_lengths)
+        print(
+            "session-balanced sampler on "
+            + ", ".join(f"{n}={k}" for n, k in zip(split["train"], train_lengths)),
+            flush=True,
+        )
+
+    set_seed(int(cfg["seed"]))
+    model, info = train_model(x_tr, y_tr, x_val, y_val, cfg, mask, sample_weights=sample_weights)
+    device = next(model.parameters()).device
+    val_pred = predict(model, x_val, int(cfg["batch_size"]), device)
+    val_score = balanced_accuracy(y_val, val_pred, len(cfg["classes"]))
+    test_pred = predict(model, x_te, int(cfg["batch_size"]), device)
+    test_score = balanced_accuracy(y_te, test_pred, len(cfg["classes"]))
+    conf = confusion(y_te, test_pred, len(cfg["classes"]))
+    print(f"val balanced accuracy {val_score:.3f}  (early stop only)", flush=True)
+    print(f"test balanced accuracy {test_score:.3f}  (not used for weights)", flush=True)
+    ship_epochs = max(1, int(info["best_epoch"]))
+
+    if cfg.get("loso"):
+        pool = split["train"] + split["val"]
+        print("leave-one-session-out on train+val only. Test stays sealed.", flush=True)
+        scores = []
+        for name in pool:
+            i = names.index(name)
+            others = [names.index(n) for n in pool if n != name]
+            tr_x, tr_y = _concat([xs[j] for j in others], [ys[j] for j in others])
+            # The held-out session is scored only. It is not used for early stopping.
+            fold, _ = train_model(tr_x, tr_y, None, None, cfg, mask, epochs=ship_epochs)
+            pred = predict(fold, xs[i], int(cfg["batch_size"]), next(fold.parameters()).device)
+            score = balanced_accuracy(ys[i], pred, len(cfg["classes"]))
+            scores.append({"session": name, "balanced_accuracy": score})
+            print(f"  {name} {score:.3f}", flush=True)
+            (out / "loso.json").write_text(json.dumps(scores, indent=2), encoding="utf-8")
+
+    onnx_path = out / "model.onnx"
+    export_onnx(model, onnx_path, cfg["classes"])
+    torch.save(
+        {
+            "state_dict": model.cpu().state_dict(),
+            "classes": cfg["classes"],
+            "mask": mask,
+            "split": split,
+        },
+        out / "model.pt",
+    )
+    write_contract(out / "contract.json", cfg, mask, split)
+    summary = {
+        "n_sessions": len(names),
+        "n_windows": int(len(y_tr) + len(y_val) + len(y_te)),
+        "n_train": int(len(y_tr)),
+        "class_counts": counts,
+        "split": split,
+        "val_balanced_accuracy": val_score,
+        "test_balanced_accuracy": test_score,
+        "confusion": conf.tolist(),
+        "ship_epochs": ship_epochs,
+        "device": info["device"],
+        "onnx": str(onnx_path),
+        "channel_keep": mask,
+        "session_balanced": bool(cfg.get("session_balanced")),
+        "window_sec": float(cfg["window_sec"]),
+        "warnings": [w for s in sessions for w in s.warnings],
+    }
+    write_report(out / "report.md", summary)
+    print(f"wrote {onnx_path}")
+    print(f"contract {out / 'contract.json'}")
+    return 0

aura_pipeline/config.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+CLASSES_DEFAULT = ["rest", "fist", "open", "pinch", "point", "thumb-up"]
+
+
+def load_config(path: Path | None = None) -> dict:
+    cfg_path = path or (ROOT / "config.yaml")
+    with cfg_path.open(encoding="utf-8") as f:
+        cfg = yaml.safe_load(f)
+    if not isinstance(cfg, dict):
+        raise SystemExit(f"Config is empty: {cfg_path}")
+    cfg["_path"] = str(cfg_path)
+    cfg.setdefault("classes", CLASSES_DEFAULT)
+    cfg.setdefault("drop_channels", [])
+    cfg.setdefault("fallback_data_dir", None)
+    return cfg
+
+
+def resolve_dir(root: Path, value: str | None) -> Path | None:
+    if not value:
+        return None
+    path = Path(value)
+    if not path.is_absolute():
+        path = root / path
+    return path.resolve()

aura_pipeline/data.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from .signal import causal_filter, design_sos, mains_ratio, robust_scale, to_rate
+
+N_CH = 8
+CHANNEL_NAMES = [f"ch{i}" for i in range(1, N_CH + 1)]
+LABEL_ALIASES = {
+    "open-hand": "open",
+    "openhand": "open",
+    "thumbup": "thumb-up",
+    "thumbs-up": "thumb-up",
+    "thumb-up": "thumb-up",
+}
+POSE_DEFAULT = [
+    "thumb_curl",
+    "index_curl",
+    "middle_curl",
+    "ring_curl",
+    "pinky_curl",
+    "pinch",
+    "openness",
+]
+
+
+def pose_target_names(cfg: dict) -> list[str]:
+    names = cfg.get("pose_targets") or POSE_DEFAULT
+    return [str(n) for n in names]
+
+
+@dataclass
+class Session:
+    name: str
+    path: str
+    fs: float
+    emg_uv: np.ndarray
+    emg: np.ndarray
+    labels: np.ndarray
+    scale: np.ndarray
+    hard_fail: list[bool]
+    qc_rows: list[dict] = field(default_factory=list)
+    n_raw: int = 0
+    n_used: int = 0
+    warnings: list[str] = field(default_factory=list)
+    pose: np.ndarray | None = None
+    pose_conf: np.ndarray | None = None
+    pose_names: list[str] = field(default_factory=list)
+
+
+def discover(folder: Path) -> list[Path]:
+    files = []
+    for path in sorted(folder.iterdir() if folder.is_dir() else []):
+        if path.name.startswith("~$"):
+            continue
+        if path.suffix.lower() in {".xlsx", ".xls", ".csv"}:
+            files.append(path)
+    return files
+
+
+def _norm_label(value, classes: set[str]) -> str | None:
+    if value is None or (isinstance(value, float) and np.isnan(value)):
+        return None
+    if pd.isna(value):
+        return None
+    text = str(value).strip().lower().replace("_", "-").replace(" ", "-")
+    text = LABEL_ALIASES.get(text, text)
+    return text if text in classes else None
+
+
+def _flag(series: pd.Series | None, n: int) -> np.ndarray:
+    if series is None:
+        return np.zeros(n, dtype=bool)
+    num = pd.to_numeric(series, errors="coerce").to_numpy()
+    return np.nan_to_num(num, nan=0.0) > 0.5
+
+
+def load_table(path: Path) -> pd.DataFrame:
+    if path.suffix.lower() == ".csv":
+        return pd.read_csv(path)
+    return pd.read_excel(path, sheet_name=0)
+
+
+def _pose_arrays(df: pd.DataFrame, names: list[str]) -> tuple[np.ndarray | None, np.ndarray | None]:
+    """Continuous pose target and its per-sample confidence, or (None, None) if absent."""
+    if not names or not all(n in df.columns for n in names):
+        return None, None
+    pose = df[names].apply(pd.to_numeric, errors="coerce").to_numpy(dtype=np.float32)
+    if "optical_conf" in df.columns:
+        conf = pd.to_numeric(df["optical_conf"], errors="coerce").to_numpy(dtype=np.float32)
+    else:
+        conf = np.ones(len(df), dtype=np.float32)
+    if "optical_present" in df.columns:
+        present = pd.to_numeric(df["optical_present"], errors="coerce").to_numpy(dtype=np.float32)
+        conf = conf * np.nan_to_num(present, nan=0.0)
+    return pose, conf
+
+
+def _hard_fail(ch: np.ndarray) -> tuple[bool, str]:
+    finite = ch[np.isfinite(ch)]
+    if finite.size < 16:
+        return True, "empty"
+    std = float(np.std(finite))
+    ptp = float(np.ptp(finite))
+    if std < 1.0 or ptp < 2.0:
+        return True, "flat"
+    # Stuck near one rail.
+    close = np.mean((np.abs(finite - finite.min()) < 1.0) | (np.abs(finite - finite.max()) < 1.0))
+    if ptp > 50.0 and close > 0.98:
+        return True, "railed"
+    return False, "ok"
+
+
+def load_session(path: Path, cfg: dict) -> Session:
+    classes = set(cfg["classes"])
+    df = load_table(path)
+    missing = [c for c in ["t", *CHANNEL_NAMES, "label"] if c not in df.columns]
+    if missing:
+        raise ValueError(f"{path.name} is missing columns: {', '.join(missing)}")
+
+    if "emg_new" in df.columns:
+        keep = pd.to_numeric(df["emg_new"], errors="coerce").fillna(0).to_numpy() > 0.5
+        df = df.loc[keep].reset_index(drop=True)
+
+    raw = df[CHANNEL_NAMES].apply(pd.to_numeric, errors="coerce").to_numpy(dtype=np.float64)
+    finite_row = np.isfinite(raw).all(axis=1)
+    t = pd.to_numeric(df["t"], errors="coerce").to_numpy(dtype=np.float64)
+    finite_row &= np.isfinite(t)
+    df = df.loc[finite_row].reset_index(drop=True)
+    raw = raw[finite_row]
+    t = t[finite_row]
+    n_raw = int(len(df))
+
+    labels = np.array([_norm_label(v, classes) for v in df["label"]], dtype=object)
+    if "label_source" in df.columns:
+        source = df["label_source"].astype(str).str.strip().str.lower().to_numpy()
+        guided = source == "guided"
+        labels = np.where(guided, labels, None)
+
+    if cfg.get("drop_optical_disagreement", False) and "optical_class" in df.columns:
+        present = _flag(df["optical_present"] if "optical_present" in df.columns else None, len(df))
+        conf = pd.to_numeric(df["optical_conf"], errors="coerce").fillna(0).to_numpy() if "optical_conf" in df.columns else np.ones(len(df))
+        optical = np.array([_norm_label(v, classes) for v in df["optical_class"]], dtype=object)
+        disagree = present & (conf >= float(cfg.get("optical_conf_min", 0.6)))
+        for i in range(len(labels)):
+            if not disagree[i] or labels[i] is None or optical[i] is None:
+                continue
+            pair = {labels[i], optical[i]}
+            if pair == {"rest", "open"}:
+                continue
+            if optical[i] != labels[i]:
+                labels[i] = None
+
+    target_fs = float(cfg["sample_rate_hz"])
+    raw32, fs, resampled_n = to_rate(raw.astype(np.float32), t, target_fs)
+    pose_names = pose_target_names(cfg)
+    pose, pose_conf = _pose_arrays(df, pose_names)
+    warnings = []
+    if resampled_n is not None:
+        idx = np.clip(np.round(np.linspace(0, len(labels) - 1, resampled_n)).astype(int), 0, len(labels) - 1)
+        labels = labels[idx]
+        if pose is not None:
+            pose = pose[idx]
+            pose_conf = pose_conf[idx]
+        warnings.append(f"resampled toward {target_fs:.0f} Hz")
+    elif abs(fs - target_fs) / target_fs > 0.005:
+        warnings.append(f"sample rate {fs:.1f} Hz, filtered as {target_fs:.0f}")
+
+    mains = mains_ratio(raw32, target_fs, float(cfg.get("notch_mains_hz", 50.0)))
+    filtered = causal_filter(raw32, design_sos(target_fs, cfg))
+    warmup = int(0.5 * target_fs)
+    if len(filtered) > warmup + 8:
+        filtered = filtered[warmup:]
+        labels = labels[warmup:]
+        raw32 = raw32[warmup:]
+        if pose is not None:
+            pose = pose[warmup:]
+            pose_conf = pose_conf[warmup:]
+
+    forced = {int(c) for c in cfg.get("drop_channels") or []}
+    hard = []
+    rows = []
+    rest = labels == "rest"
+    active = np.array([v is not None and v != "rest" for v in labels])
+    for i in range(N_CH):
+        failed, reason = _hard_fail(filtered[:, i])
+        if (i + 1) in forced:
+            failed, reason = True, "forced"
+        snr = np.nan
+        if rest.sum() > 8 and active.sum() > 8:
+            snr = float(np.sqrt(np.mean(filtered[active, i] ** 2)) / (np.sqrt(np.mean(filtered[rest, i] ** 2)) + 1e-6))
+        hard.append(failed)
+        rows.append({
+            "session": path.stem,
+            "channel": i + 1,
+            "std_uv": float(np.std(filtered[:, i])),
+            "snr": None if not np.isfinite(snr) else round(snr, 3),
+            "mains_ratio": None if not np.isfinite(mains[i]) else round(float(mains[i]), 3),
+            "verdict": "drop" if failed else "keep",
+            "reason": reason,
+        })
+
+    masked = filtered.copy()
+    for i, failed in enumerate(hard):
+        if failed:
+            masked[:, i] = 0.0
+    scale = robust_scale(masked)
+    scaled = (masked / scale).astype(np.float32)
+
+    return Session(
+        name=path.stem,
+        path=str(path),
+        fs=target_fs,
+        emg_uv=filtered.astype(np.float32),
+        emg=scaled,
+        labels=labels,
+        scale=scale,
+        hard_fail=hard,
+        qc_rows=rows,
+        n_raw=n_raw,
+        n_used=int(len(scaled)),
+        warnings=warnings,
+        pose=None if pose is None else pose.astype(np.float32),
+        pose_conf=None if pose_conf is None else pose_conf.astype(np.float32),
+        pose_names=pose_names if pose is not None else [],
+    )
+
+
+def trim_transitions(labels: np.ndarray, edge: int) -> np.ndarray:
+    out = labels.copy()
+    if edge <= 0 or len(out) < 2:
+        return out
+    change = np.zeros(len(out), dtype=bool)
+    change[1:] = out[1:] != out[:-1]
+    for i in np.flatnonzero(change):
+        lo = max(0, i - edge)
+        hi = min(len(out), i + edge)
+        out[lo:hi] = None
+    return out
+
+
+def make_windows(session: Session, cfg: dict) -> tuple[np.ndarray, np.ndarray]:
+    fs = session.fs
+    win = int(round(float(cfg["window_sec"]) * fs))
+    hop = int(round(float(cfg["hop_sec"]) * fs))
+    edge = int(round(float(cfg["edge_trim_sec"]) * fs))
+    if win < 128 or hop < 1:
+        raise ValueError("window_sec must cover at least 128 samples and hop_sec must be positive")
+    labels = trim_transitions(session.labels, edge)
+    xs, ys = [], []
+    class_to_i = {name: i for i, name in enumerate(cfg["classes"])}
+    min_frac = float(cfg.get("min_label_fraction", 0.9))
+    for start in range(0, len(labels) - win + 1, hop):
+        chunk = labels[start:start + win]
+        named = [v for v in chunk if v is not None]
+        if len(named) / win < min_frac:
+            continue
+        name = max(set(named), key=named.count)
+        if named.count(name) / win < min_frac:
+            continue
+        if any(v not in (None, name) for v in chunk):
+            continue
+        xs.append(session.emg[start:start + win])
+        ys.append(class_to_i[name])
+    if not xs:
+        return np.empty((0, win, N_CH), np.float32), np.empty((0,), np.int64)
+    return np.stack(xs).astype(np.float32), np.asarray(ys, dtype=np.int64)
+
+
+def global_mask(sessions: list[Session], cfg: dict) -> list[bool]:
+    """True = keep. A channel is removed only when hard-fail is common across files."""
+    if not sessions or not cfg.get("auto_drop_hard_failures", True):
+        mask = [True] * N_CH
+    else:
+        frac = float(cfg.get("global_drop_fraction", 0.5))
+        fails = np.mean([[1.0 if f else 0.0 for f in s.hard_fail] for s in sessions], axis=0)
+        mask = [bool(v < frac) for v in fails]
+    for ch in cfg.get("drop_channels") or []:
+        idx = int(ch) - 1
+        if 0 <= idx < N_CH:
+            mask[idx] = False
+    if not any(mask):
+        raise SystemExit("Channel QC dropped every channel. Clear drop_channels or check the recordings.")
+    return mask
+
+
+def apply_mask(windows: np.ndarray, mask: list[bool]) -> np.ndarray:
+    if windows.size == 0:
+        return windows
+    out = windows.copy()
+    for i, keep in enumerate(mask):
+        if not keep:
+            out[:, :, i] = 0.0
+    return out

aura_pipeline/export.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import torch
+
+from .model import AuraNet, ProbModel
+
+
+def export_onnx(model: AuraNet, path: Path, classes: list[str]) -> None:
+    model = model.cpu().eval()
+    wrapper = ProbModel(model).eval()
+    dummy = torch.zeros(1, model.n_samples, model.n_channels, dtype=torch.float32)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        torch.onnx.export(
+            wrapper,
+            dummy,
+            str(path),
+            input_names=["emg"],
+            output_names=["probs"],
+            dynamic_axes={"emg": {0: "batch"}, "probs": {0: "batch"}},
+            opset_version=17,
+            dynamo=False,
+        )
+    except TypeError:
+        torch.onnx.export(
+            wrapper,
+            dummy,
+            str(path),
+            input_names=["emg"],
+            output_names=["probs"],
+            dynamic_axes={"emg": {0: "batch"}, "probs": {0: "batch"}},
+            opset_version=17,
+        )
+    _check_ort(path, dummy.numpy(), len(classes))
+
+
+def _check_ort(path: Path, dummy, n_classes: int) -> None:
+    import onnxruntime as ort
+
+    sess = ort.InferenceSession(str(path), providers=["CPUExecutionProvider"])
+    probs = sess.run(None, {"emg": dummy})[0]
+    if probs.shape != (1, n_classes):
+        raise RuntimeError(f"ONNX output shape {probs.shape}, expected (1, {n_classes})")
+    total = float(probs.sum())
+    if abs(total - 1.0) > 1e-3:
+        raise RuntimeError(f"ONNX probabilities sum to {total}, expected 1")
+
+
+def write_contract(path: Path, cfg: dict, mask: list[bool], split: dict[str, list[str]]) -> None:
+    fs = float(cfg["sample_rate_hz"])
+    win = int(round(float(cfg["window_sec"]) * fs))
+    contract = {
+        "format": "aura-hand-onnx-v1",
+        "task": "6-class palm EMG, probabilities",
+        "input_name": "emg",
+        "input_layout": "NTC",
+        "input_shape": [1, win, 8],
+        "input_dtype": "float32",
+        "output_name": "probs",
+        "output_shape": [1, len(cfg["classes"])],
+        "classes": list(cfg["classes"]),
+        "sample_rate_hz": fs,
+        "window_samples": win,
+        "hop_samples": int(round(float(cfg["hop_sec"]) * fs)),
+        "channel_names": [f"ch{i}" for i in range(1, 9)],
+        "channel_keep": mask,
+        "preprocess": {
+            "in_graph": False,
+            "unit": "microvolts, then per-channel robust scale",
+            "scale": "median(abs(x)) / 0.6745, floor 1e-6, per recording over the filtered signal",
+            "filter": "causal sos: bandpass 20-120 order 4, bandstop 45-55 order 4, notch 100 Q=30",
+            "note": "Apply the filter and scale before this model. Dropped channels may be left as-is; the graph zeros them.",
+        },
+        "imu_used": False,
+        "optical_used_as_input": False,
+        "split_unit": "session file, not window",
+        "trained_on": split["train"],
+        "early_stop_on": split["val"],
+        "tested_on": split["test"],
+        "test_used_for_weights": False,
+    }
+    path.write_text(json.dumps(contract, indent=2), encoding="utf-8")

aura_pipeline/fit.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import numpy as np
+import torch
+from torch import nn
+from torch.utils.data import DataLoader, TensorDataset, WeightedRandomSampler
+
+from .model import AuraNet
+
+
+def set_seed(seed: int) -> None:
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+
+
+def class_weights(y: np.ndarray, n_classes: int) -> torch.Tensor:
+    counts = np.bincount(y, minlength=n_classes).astype(np.float64)
+    weights = np.zeros(n_classes, dtype=np.float32)
+    present = counts > 0
+    weights[present] = counts[present].sum() / (present.sum() * counts[present])
+    return torch.tensor(weights)
+
+
+def balanced_accuracy(y_true: np.ndarray, y_pred: np.ndarray, n_classes: int) -> float:
+    scores = []
+    for c in range(n_classes):
+        mask = y_true == c
+        if mask.sum() == 0:
+            continue
+        scores.append(float(np.mean(y_pred[mask] == c)))
+    return float(np.mean(scores)) if scores else 0.0
+
+
+def confusion(y_true: np.ndarray, y_pred: np.ndarray, n_classes: int) -> np.ndarray:
+    mat = np.zeros((n_classes, n_classes), dtype=np.int64)
+    for t, p in zip(y_true, y_pred):
+        mat[int(t), int(p)] += 1
+    return mat
+
+
+def session_sample_weights(session_lengths: list[int]) -> np.ndarray:
+    """Per-window weights so each session has equal mass, regardless of window count."""
+    weights = []
+    for n in session_lengths:
+        if n <= 0:
+            continue
+        weights.append(np.full(n, 1.0 / n, dtype=np.float64))
+    if not weights:
+        return np.empty((0,), np.float64)
+    return np.concatenate(weights)
+
+
+def _loader(
+    x: np.ndarray,
+    y: np.ndarray,
+    batch: int,
+    shuffle: bool,
+    sample_weights: np.ndarray | None = None,
+) -> DataLoader:
+    ds = TensorDataset(torch.from_numpy(x), torch.from_numpy(y))
+    if sample_weights is None:
+        return DataLoader(ds, batch_size=batch, shuffle=shuffle)
+    sampler = WeightedRandomSampler(
+        torch.as_tensor(sample_weights, dtype=torch.double),
+        num_samples=len(sample_weights),
+        replacement=True,
+    )
+    return DataLoader(ds, batch_size=batch, sampler=sampler)
+
+
+@torch.no_grad()
+def predict(model: nn.Module, x: np.ndarray, batch: int, device: torch.device) -> np.ndarray:
+    model.eval()
+    out = []
+    loader = _loader(x, np.zeros(len(x), np.int64), batch, shuffle=False)
+    for xb, _ in loader:
+        logits = model(xb.to(device))
+        out.append(logits.argmax(dim=1).cpu().numpy())
+    return np.concatenate(out) if out else np.empty((0,), np.int64)
+
+
+def train_model(
+    x_train: np.ndarray,
+    y_train: np.ndarray,
+    x_val: np.ndarray | None,
+    y_val: np.ndarray | None,
+    cfg: dict,
+    channel_mask: list[bool],
+    epochs: int | None = None,
+    sample_weights: np.ndarray | None = None,
+) -> tuple[AuraNet, dict]:
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    n_classes = len(cfg["classes"])
+    win = x_train.shape[1]
+    model = AuraNet(
+        n_classes=n_classes,
+        n_channels=x_train.shape[2],
+        n_samples=win,
+        channel_mask=channel_mask,
+    ).to(device)
+    opt = torch.optim.AdamW(
+        model.parameters(),
+        lr=float(cfg["lr"]),
+        weight_decay=float(cfg["weight_decay"]),
+    )
+    loss_fn = nn.CrossEntropyLoss(weight=class_weights(y_train, n_classes).to(device))
+    loader = _loader(
+        x_train,
+        y_train,
+        int(cfg["batch_size"]),
+        shuffle=True,
+        sample_weights=sample_weights,
+    )
+    max_epochs = int(epochs if epochs is not None else cfg["epochs"])
+    patience = int(cfg["patience"])
+    best_state = None
+    best_score = -1.0
+    best_epoch = 0
+    stale = 0
+    history = []
+
+    for epoch in range(1, max_epochs + 1):
+        model.train()
+        total = 0.0
+        seen = 0
+        for xb, yb in loader:
+            xb = xb.to(device)
+            yb = yb.to(device)
+            opt.zero_grad(set_to_none=True)
+            loss = loss_fn(model(xb), yb)
+            loss.backward()
+            opt.step()
+            total += float(loss.item()) * len(xb)
+            seen += len(xb)
+        row = {"epoch": epoch, "loss": total / max(1, seen)}
+        if x_val is not None and len(x_val):
+            pred = predict(model, x_val, int(cfg["batch_size"]), device)
+            score = balanced_accuracy(y_val, pred, n_classes)
+            row["val_balanced_accuracy"] = score
+            if score > best_score + 1e-4:
+                best_score = score
+                best_epoch = epoch
+                best_state = {k: v.detach().cpu().clone() for k, v in model.state_dict().items()}
+                stale = 0
+            else:
+                stale += 1
+        else:
+            best_epoch = epoch
+            best_state = {k: v.detach().cpu().clone() for k, v in model.state_dict().items()}
+        history.append(row)
+        score_txt = f"{row['val_balanced_accuracy']:.3f}" if "val_balanced_accuracy" in row else "-"
+        print(f"  epoch {epoch:02d}  loss {row['loss']:.4f}  val bal-acc {score_txt}", flush=True)
+        if x_val is not None and stale >= patience:
+            print(f"  early stop at epoch {epoch}", flush=True)
+            break
+
+    if best_state is not None:
+        model.load_state_dict(best_state)
+    model.to(device)
+    info = {
+        "device": str(device),
+        "best_epoch": best_epoch,
+        "best_balanced_accuracy": None if best_score < 0 else best_score,
+        "history": history,
+    }
+    return model, info

aura_pipeline/model.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+
+
+class AuraNet(nn.Module):
+    """Temporal-spatial EMG classifier.
+
+    Input is (batch, time, channels). Dropped channels are zeroed by a mask stored in the graph.
+    """
+
+    def __init__(
+        self,
+        n_classes: int = 6,
+        n_channels: int = 8,
+        n_samples: int = 250,
+        dropout: float = 0.3,
+        channel_mask: list[bool] | None = None,
+    ):
+        super().__init__()
+        f1, depth = 8, 2
+        f2 = f1 * depth
+        self.n_samples = n_samples
+        self.n_channels = n_channels
+        mask = channel_mask if channel_mask is not None else [True] * n_channels
+        self.register_buffer(
+            "channel_mask",
+            torch.tensor([1.0 if k else 0.0 for k in mask], dtype=torch.float32),
+        )
+        self.temporal = nn.Conv2d(1, f1, (1, 64), padding=(0, 32), bias=False)
+        self.bn1 = nn.BatchNorm2d(f1)
+        self.spatial = nn.Conv2d(f1, f2, (n_channels, 1), groups=f1, bias=False)
+        self.bn2 = nn.BatchNorm2d(f2)
+        self.pool1 = nn.AvgPool2d((1, 4))
+        self.drop1 = nn.Dropout(dropout)
+        self.sep_dw = nn.Conv2d(f2, f2, (1, 16), padding=(0, 8), groups=f2, bias=False)
+        self.sep_pw = nn.Conv2d(f2, f2, (1, 1), bias=False)
+        self.bn3 = nn.BatchNorm2d(f2)
+        self.pool2 = nn.AvgPool2d((1, 8))
+        self.drop2 = nn.Dropout(dropout)
+        feat = self._probe(n_samples, n_channels)
+        self.head = nn.Linear(feat, n_classes)
+        self._reset_bn()
+
+    def _reset_bn(self) -> None:
+        for module in self.modules():
+            if isinstance(module, nn.BatchNorm2d):
+                module.reset_running_stats()
+
+    def _probe(self, n_samples: int, n_channels: int) -> int:
+        was = self.training
+        self.eval()
+        with torch.no_grad():
+            y = self.features(torch.zeros(1, n_samples, n_channels))
+        self.train(was)
+        if y.shape[-1] < 1:
+            raise ValueError("Window is too short for this network. Use at least 1 second at 250 Hz.")
+        return int(y.shape[-1])
+
+    def features(self, x: torch.Tensor) -> torch.Tensor:
+        x = x * self.channel_mask.view(1, 1, -1)
+        x = x.permute(0, 2, 1).unsqueeze(1)
+        x = self.bn1(self.temporal(x))
+        x = F.elu(self.bn2(self.spatial(x)))
+        x = self.drop1(self.pool1(x))
+        x = F.elu(self.bn3(self.sep_pw(self.sep_dw(x))))
+        x = self.drop2(self.pool2(x))
+        return torch.flatten(x, 1)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.head(self.features(x))
+
+
+class ProbModel(nn.Module):
+    """Wraps AuraNet so the exported output is class probabilities, not logits."""
+
+    def __init__(self, net: AuraNet):
+        super().__init__()
+        self.net = net
+
+    def forward(self, emg: torch.Tensor) -> torch.Tensor:
+        return torch.softmax(self.net(emg), dim=-1)

aura_pipeline/pose.py

@@ -0,0 +1,405 @@
+"""Continuous hand-pose regression from palm EMG.
+
+Parallel to the classifier. The target is the optical hand tracker carried in each
+session file (per-finger curls plus pinch and openness), not motion capture. The model
+distils that optical stream into the 8-channel EMG, so its ceiling is the tracker's own
+quality. Output is one pose vector per window, each DoF in [0, 1].
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+import torch
+from torch import nn
+from torch.utils.data import DataLoader, TensorDataset
+
+from .data import N_CH, apply_mask, pose_target_names
+from .fit import set_seed
+from .model import AuraNet
+
+
+class PoseNet(nn.Module):
+    """AuraNet backbone with a sigmoid head. Output is a pose vector in [0, 1]."""
+
+    def __init__(
+        self,
+        n_dof: int,
+        n_channels: int = N_CH,
+        n_samples: int = 250,
+        channel_mask: list[bool] | None = None,
+    ):
+        super().__init__()
+        self.net = AuraNet(
+            n_classes=n_dof,
+            n_channels=n_channels,
+            n_samples=n_samples,
+            channel_mask=channel_mask,
+        )
+        self.n_dof = n_dof
+        self.n_channels = n_channels
+        self.n_samples = n_samples
+
+    def forward(self, emg: torch.Tensor) -> torch.Tensor:
+        return torch.sigmoid(self.net(emg))
+
+
+def make_pose_windows(
+    session, cfg: dict, names: list[str]
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Windows of EMG paired with a confidence-weighted pose target.
+
+    A window is kept when at least half its samples carry a valid, present pose and the
+    median optical confidence clears ``pose_min_conf``. The target is the per-DoF median
+    over the valid samples; the sample weight is that median confidence.
+    """
+    n_dof = len(names)
+    win = int(round(float(cfg["window_sec"]) * session.fs))
+    empty = (
+        np.empty((0, win, N_CH), np.float32),
+        np.empty((0, n_dof), np.float32),
+        np.empty((0,), np.float32),
+    )
+    if session.pose is None or session.pose_conf is None:
+        return empty
+    hop = int(round(float(cfg["hop_sec"]) * session.fs))
+    min_conf = float(cfg.get("pose_min_conf", 0.3))
+    pose = session.pose
+    conf = session.pose_conf
+    emg = session.emg
+    n = min(len(emg), len(pose), len(conf))
+    xs, ys, ws = [], [], []
+    for start in range(0, n - win + 1, hop):
+        seg = pose[start:start + win]
+        c = conf[start:start + win]
+        valid = np.isfinite(seg).all(axis=1) & np.isfinite(c)
+        if valid.mean() < 0.5:
+            continue
+        cv = c[valid]
+        med_conf = float(np.median(cv))
+        if med_conf < min_conf:
+            continue
+        xs.append(emg[start:start + win])
+        ys.append(np.median(seg[valid], axis=0).astype(np.float32))
+        ws.append(med_conf)
+    if not xs:
+        return empty
+    return (
+        np.stack(xs).astype(np.float32),
+        np.stack(ys).astype(np.float32),
+        np.asarray(ws, dtype=np.float32),
+    )
+
+
+def pose_metrics(y_true: np.ndarray, y_pred: np.ndarray, names: list[str]) -> dict:
+    per = []
+    for j, name in enumerate(names):
+        t = y_true[:, j]
+        p = y_pred[:, j]
+        mae = float(np.mean(np.abs(t - p))) if len(t) else float("nan")
+        if len(t) > 1 and np.std(t) > 1e-6 and np.std(p) > 1e-6:
+            r = float(np.corrcoef(t, p)[0, 1])
+        else:
+            r = float("nan")
+        per.append({"dof": name, "mae": mae, "r": r})
+    maes = [d["mae"] for d in per if np.isfinite(d["mae"])]
+    rs = [d["r"] for d in per if np.isfinite(d["r"])]
+    return {
+        "per_dof": per,
+        "mae": float(np.mean(maes)) if maes else float("nan"),
+        "r": float(np.mean(rs)) if rs else float("nan"),
+    }
+
+
+@torch.no_grad()
+def predict_pose(model: nn.Module, x: np.ndarray, batch: int, device: torch.device) -> np.ndarray:
+    model.eval()
+    n_dof = getattr(model, "n_dof", 0)
+    if len(x) == 0:
+        return np.empty((0, n_dof), np.float32)
+    loader = DataLoader(TensorDataset(torch.from_numpy(x)), batch_size=batch, shuffle=False)
+    out = [model(xb.to(device)).cpu().numpy() for (xb,) in loader]
+    return np.concatenate(out)
+
+
+def train_pose(
+    x_tr: np.ndarray,
+    y_tr: np.ndarray,
+    w_tr: np.ndarray,
+    x_val: np.ndarray | None,
+    y_val: np.ndarray | None,
+    cfg: dict,
+    names: list[str],
+    channel_mask: list[bool],
+    epochs: int | None = None,
+) -> tuple[PoseNet, dict]:
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    model = PoseNet(len(names), x_tr.shape[2], x_tr.shape[1], channel_mask).to(device)
+    opt = torch.optim.AdamW(
+        model.parameters(),
+        lr=float(cfg["lr"]),
+        weight_decay=float(cfg["weight_decay"]),
+    )
+    loss_fn = nn.SmoothL1Loss(beta=float(cfg.get("pose_loss_beta", 0.1)), reduction="none")
+    ds = TensorDataset(torch.from_numpy(x_tr), torch.from_numpy(y_tr), torch.from_numpy(w_tr))
+    loader = DataLoader(ds, batch_size=int(cfg["batch_size"]), shuffle=True)
+    max_epochs = int(epochs if epochs is not None else cfg["epochs"])
+    patience = int(cfg["patience"])
+    best_state = None
+    best_mae = float("inf")
+    best_epoch = 0
+    stale = 0
+    history = []
+
+    for epoch in range(1, max_epochs + 1):
+        model.train()
+        total = 0.0
+        seen = 0
+        for xb, yb, wb in loader:
+            xb = xb.to(device)
+            yb = yb.to(device)
+            wb = wb.to(device)
+            opt.zero_grad(set_to_none=True)
+            per = loss_fn(model(xb), yb).mean(dim=1)
+            loss = (per * wb).sum() / (wb.sum() + 1e-8)
+            loss.backward()
+            opt.step()
+            total += float(loss.item()) * len(xb)
+            seen += len(xb)
+        row = {"epoch": epoch, "loss": total / max(1, seen)}
+        if x_val is not None and len(x_val):
+            metrics = pose_metrics(y_val, predict_pose(model, x_val, int(cfg["batch_size"]), device), names)
+            row["val_mae"] = metrics["mae"]
+            row["val_r"] = metrics["r"]
+            if metrics["mae"] < best_mae - 1e-5:
+                best_mae = metrics["mae"]
+                best_epoch = epoch
+                best_state = {k: v.detach().cpu().clone() for k, v in model.state_dict().items()}
+                stale = 0
+            else:
+                stale += 1
+        else:
+            best_epoch = epoch
+            best_state = {k: v.detach().cpu().clone() for k, v in model.state_dict().items()}
+        history.append(row)
+        vmae = f"{row['val_mae']:.4f}" if "val_mae" in row else "-"
+        vr = f"{row['val_r']:.3f}" if "val_r" in row else "-"
+        print(f"  epoch {epoch:02d}  loss {row['loss']:.4f}  val mae {vmae}  val r {vr}", flush=True)
+        if x_val is not None and stale >= patience:
+            print(f"  early stop at epoch {epoch}", flush=True)
+            break
+
+    if best_state is not None:
+        model.load_state_dict(best_state)
+    model.to(device)
+    info = {
+        "device": str(device),
+        "best_epoch": best_epoch,
+        "best_val_mae": None if best_mae == float("inf") else best_mae,
+        "history": history,
+    }
+    return model, info
+
+
+def export_pose_onnx(model: PoseNet, path: Path, names: list[str]) -> None:
+    model = model.cpu().eval()
+    dummy = torch.zeros(1, model.n_samples, model.n_channels, dtype=torch.float32)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    kwargs = dict(
+        input_names=["emg"],
+        output_names=["pose"],
+        dynamic_axes={"emg": {0: "batch"}, "pose": {0: "batch"}},
+        opset_version=17,
+    )
+    try:
+        torch.onnx.export(model, dummy, str(path), dynamo=False, **kwargs)
+    except TypeError:
+        torch.onnx.export(model, dummy, str(path), **kwargs)
+    _check_ort(path, dummy.numpy(), len(names))
+
+
+def _check_ort(path: Path, dummy, n_dof: int) -> None:
+    import onnxruntime as ort
+
+    sess = ort.InferenceSession(str(path), providers=["CPUExecutionProvider"])
+    out = sess.run(None, {"emg": dummy})[0]
+    if out.shape != (1, n_dof):
+        raise RuntimeError(f"ONNX pose shape {out.shape}, expected (1, {n_dof})")
+    if float(out.min()) < -1e-4 or float(out.max()) > 1.0 + 1e-4:
+        raise RuntimeError("ONNX pose outputs fall outside [0, 1]")
+
+
+def write_pose_contract(path: Path, cfg: dict, names: list[str], mask: list[bool], split: dict) -> None:
+    fs = float(cfg["sample_rate_hz"])
+    win = int(round(float(cfg["window_sec"]) * fs))
+    contract = {
+        "format": "aura-pose-onnx-v1",
+        "task": "continuous hand-pose regression from palm EMG",
+        "input_name": "emg",
+        "input_layout": "NTC",
+        "input_shape": [1, win, N_CH],
+        "input_dtype": "float32",
+        "output_name": "pose",
+        "output_shape": [1, len(names)],
+        "output_range": [0, 1],
+        "dof": list(names),
+        "sample_rate_hz": fs,
+        "window_samples": win,
+        "hop_samples": int(round(float(cfg["hop_sec"]) * fs)),
+        "channel_names": [f"ch{i}" for i in range(1, N_CH + 1)],
+        "channel_keep": mask,
+        "preprocess": {
+            "in_graph": False,
+            "unit": "microvolts, then per-channel robust scale",
+            "scale": "median(abs(x)) / 0.6745, floor 1e-6, per recording over the filtered signal",
+            "filter": "causal sos: bandpass 20-120 order 4, bandstop 45-55 order 4, notch 100 Q=30",
+            "note": "Apply the filter and scale before this model. Dropped channels may be left as-is; the graph zeros them.",
+        },
+        "target_source": "optical hand tracker carried in the session file, not motion capture",
+        "imu_used": False,
+        "split_unit": "session file, not window",
+        "trained_on": split["train"],
+        "early_stop_on": split["val"],
+        "tested_on": split["test"],
+        "test_used_for_weights": False,
+    }
+    path.write_text(json.dumps(contract, indent=2), encoding="utf-8")
+
+
+def _fmt(value) -> str:
+    return "n/a" if value is None or not np.isfinite(value) else f"{value:.4f}"
+
+
+def write_pose_report(
+    path: Path,
+    names: list[str],
+    split: dict,
+    val_metrics: dict | None,
+    test_metrics: dict | None,
+    info: dict,
+    mask: list[bool],
+    counts: dict,
+) -> None:
+    lines = [
+        "# Aura hand-pose regression run",
+        "",
+        "Target is the optical hand tracker carried in the session files, not motion capture.",
+        "The model distils that stream into EMG, so its ceiling is the tracker's quality.",
+        "",
+        f"- Train sessions ({len(split['train'])}): {', '.join(split['train'])}",
+        f"- Val sessions ({len(split['val'])}): {', '.join(split['val'])}",
+        f"- Test sessions ({len(split['test'])}): {', '.join(split['test'])}",
+        f"- Windows: train={counts['train']} val={counts['val']} test={counts['test']}",
+        f"- Val mean MAE (early stop only): {_fmt(val_metrics['mae']) if val_metrics else 'n/a'}",
+        f"- Test mean MAE (never used to train): {_fmt(test_metrics['mae']) if test_metrics else 'n/a'}",
+        f"- Test mean r: {_fmt(test_metrics['r']) if test_metrics else 'n/a'}",
+        f"- Epoch kept: {info['best_epoch']}",
+        f"- Device: {info['device']}",
+        f"- Window: {counts.get('window_sec', 1.0)} s",
+        "",
+        "## Per-DoF test error",
+        "",
+        "| DoF | MAE | r |",
+        "| --- | --- | --- |",
+    ]
+    test_per = {d["dof"]: d for d in (test_metrics["per_dof"] if test_metrics else [])}
+    for name in names:
+        row = test_per.get(name)
+        mae = _fmt(row["mae"]) if row else "n/a"
+        r = _fmt(row["r"]) if row else "n/a"
+        lines.append(f"| {name} | {mae} | {r} |")
+    lines += [
+        "",
+        "MAE is in target units (each DoF is [0, 1]). r is Pearson correlation on the test sessions.",
+        "Copy `split.json` into config.yaml to freeze this split.",
+        "",
+    ]
+    path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def run_pose(sessions, cfg: dict, out: Path, split: dict, mask: list[bool]) -> int:
+    names = pose_target_names(cfg)
+    if not any(s.pose is not None for s in sessions):
+        raise SystemExit("No pose columns found. Expected: " + ", ".join(names))
+
+    per_session = {}
+    for session in sessions:
+        x, y, w = make_pose_windows(session, cfg, names)
+        x = apply_mask(x, mask)
+        per_session[session.name] = (x, y, w)
+        print(f"  {session.name}: {len(x)} pose windows", flush=True)
+
+    win = int(round(float(cfg["window_sec"]) * float(cfg["sample_rate_hz"])))
+
+    def gather(role: str):
+        xs, ys, ws = [], [], []
+        for name in split[role]:
+            bundle = per_session.get(name)
+            if bundle is not None and len(bundle[0]):
+                xs.append(bundle[0])
+                ys.append(bundle[1])
+                ws.append(bundle[2])
+        if not xs:
+            return (
+                np.empty((0, win, N_CH), np.float32),
+                np.empty((0, len(names)), np.float32),
+                np.empty((0,), np.float32),
+            )
+        return np.concatenate(xs), np.concatenate(ys), np.concatenate(ws)
+
+    x_tr, y_tr, w_tr = gather("train")
+    x_val, y_val, w_val = gather("val")
+    x_te, y_te, w_te = gather("test")
+    if not len(x_tr):
+        raise SystemExit("No pose training windows. Lower pose_min_conf or check the optical columns.")
+    counts = {
+        "train": int(len(x_tr)),
+        "val": int(len(x_val)),
+        "test": int(len(x_te)),
+        "window_sec": float(cfg["window_sec"]),
+    }
+    print(f"pose windows  train={counts['train']}  val={counts['val']}  test={counts['test']}", flush=True)
+
+    set_seed(int(cfg["seed"]))
+    model, info = train_pose(x_tr, y_tr, w_tr, x_val, y_val, cfg, names, mask)
+    device = next(model.parameters()).device
+    val_metrics = (
+        pose_metrics(y_val, predict_pose(model, x_val, int(cfg["batch_size"]), device), names)
+        if len(x_val)
+        else None
+    )
+    test_metrics = (
+        pose_metrics(y_te, predict_pose(model, x_te, int(cfg["batch_size"]), device), names)
+        if len(x_te)
+        else None
+    )
+    if val_metrics:
+        print(f"val  mean mae {val_metrics['mae']:.4f}  mean r {val_metrics['r']:.3f}  (early stop only)", flush=True)
+    if test_metrics:
+        print(f"test mean mae {test_metrics['mae']:.4f}  mean r {test_metrics['r']:.3f}  (not used for weights)", flush=True)
+
+    onnx_path = out / "pose.onnx"
+    export_pose_onnx(model, onnx_path, names)
+    torch.save(
+        {"state_dict": model.cpu().state_dict(), "dof": names, "mask": mask, "split": split},
+        out / "pose.pt",
+    )
+    write_pose_contract(out / "pose_contract.json", cfg, names, mask, split)
+    write_pose_report(out / "pose_report.md", names, split, val_metrics, test_metrics, info, mask, counts)
+    summary = {
+        "dof": names,
+        "counts": counts,
+        "split": split,
+        "val": val_metrics,
+        "test": test_metrics,
+        "best_epoch": info["best_epoch"],
+        "device": info["device"],
+        "channel_keep": mask,
+        "onnx": str(onnx_path),
+    }
+    (out / "pose_report.json").write_text(json.dumps(summary, indent=2), encoding="utf-8")
+    print(f"wrote {onnx_path}")
+    print(f"contract {out / 'pose_contract.json'}")
+    return 0

aura_pipeline/report.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+
+
+def write_qc(path: Path, rows: list[dict], mask: list[bool]) -> None:
+    lines = [
+        "# Channel QC",
+        "",
+        "Hard failures (flat, empty, railed, or forced) are zeroed in that file.",
+        "A channel is removed from the shipped model only if it fails in many files.",
+        "",
+        "Shipped channel keep mask (ch1..ch8): " + " ".join("1" if k else "0" for k in mask),
+        "",
+        "| session | ch | std uV | snr | mains | verdict | reason |",
+        "| --- | --- | --- | --- | --- | --- | --- |",
+    ]
+    for row in rows:
+        snr = "" if row["snr"] is None else f"{row['snr']:.2f}"
+        mains = "" if row["mains_ratio"] is None else f"{row['mains_ratio']:.2f}"
+        lines.append(
+            f"| {row['session']} | {row['channel']} | {row['std_uv']:.1f} | {snr} | {mains} | {row['verdict']} | {row['reason']} |"
+        )
+    lines.append("")
+    path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def write_report(path: Path, summary: dict) -> None:
+    counts = summary["class_counts"]
+    lines = [
+        "# Aura hand training run",
+        "",
+        f"- Train sessions ({len(summary['split']['train'])}): {', '.join(summary['split']['train'])}",
+        f"- Val sessions ({len(summary['split']['val'])}): {', '.join(summary['split']['val'])}",
+        f"- Test sessions ({len(summary['split']['test'])}): {', '.join(summary['split']['test'])}",
+        f"- Train windows: {summary['n_train']}",
+        f"- Val balanced accuracy (early stop only): {_pct(summary.get('val_balanced_accuracy'))}",
+        f"- Test balanced accuracy (never used to train): {_pct(summary.get('test_balanced_accuracy'))}",
+        f"- Epoch kept: {summary['ship_epochs']}",
+        f"- Device: {summary['device']}",
+        f"- ONNX: `{summary['onnx']}`",
+    ]
+    extra = []
+    if summary.get("session_balanced"):
+        extra.append("- Session-balanced sampler: yes")
+    if summary.get("window_sec") not in (None, 1.0):
+        extra.append(f"- Window: {summary['window_sec']} s")
+    if extra:
+        lines[11:11] = extra
+    lines += [
+        "",
+        "## Train class counts",
+        "",
+        "| class | windows |",
+        "| --- | --- |",
+    ]
+    for name, n in counts.items():
+        lines.append(f"| {name} | {n} |")
+    lines += [
+        "",
+        "## Test confusion",
+        "",
+        "Rows are true class, columns are predicted, order is the class list in config.yaml.",
+        "This matrix is the test sessions only. Those files were not in the loss and not in early stopping.",
+        "",
+        "```",
+        np.array2string(np.asarray(summary["confusion"])) if summary.get("confusion") is not None else "n/a",
+        "```",
+        "",
+        "Copy `split.json` into config.yaml (`train_sessions`, `val_sessions`, `test_sessions`) to freeze this split.",
+        "",
+    ]
+    if summary.get("warnings"):
+        lines.append("## Warnings")
+        lines.append("")
+        for w in summary["warnings"]:
+            lines.append(f"- {w}")
+        lines.append("")
+    path.write_text("\n".join(lines), encoding="utf-8")
+    path.with_suffix(".json").write_text(json.dumps(summary, indent=2), encoding="utf-8")
+
+
+def _pct(value) -> str:
+    if value is None:
+        return "n/a"
+    return f"{float(value) * 100:.1f}%"

aura_pipeline/signal.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import numpy as np
+from scipy.signal import butter, iirnotch, resample, sosfilt, sosfilt_zi, tf2sos
+
+
+def design_sos(fs: float, cfg: dict) -> np.ndarray:
+    """Causal SOS: bandpass, mains bandstop, harmonic notch. Coefficients come from config."""
+    lo, hi = cfg["bandpass_hz"]
+    order = int(cfg["bandpass_order"])
+    mains = float(cfg["notch_mains_hz"])
+    parts = [
+        butter(order, (lo, hi), btype="bandpass", fs=fs, output="sos"),
+        butter(order, (mains - 5.0, mains + 5.0), btype="bandstop", fs=fs, output="sos"),
+        tf2sos(*iirnotch(float(cfg["notch_harmonic_hz"]), Q=float(cfg["notch_q"]), fs=fs)),
+    ]
+    return np.vstack(parts)
+
+
+def causal_filter(x: np.ndarray, sos: np.ndarray) -> np.ndarray:
+    """Forward SOS filter. Initial state is set from the first sample."""
+    if len(x) == 0:
+        return x.astype(np.float32)
+    zi = np.repeat(sosfilt_zi(sos)[:, :, None], x.shape[1], axis=2)
+    zi = zi * x[0].astype(np.float64)[None, None, :]
+    y, _ = sosfilt(sos, x.astype(np.float64), axis=0, zi=zi)
+    return y.astype(np.float32)
+
+
+def to_rate(x: np.ndarray, t: np.ndarray, target_fs: float) -> tuple[np.ndarray, float, int | None]:
+    """Return signal, sample rate, and new length if resampled."""
+    if len(t) < 3:
+        return x, target_fs, None
+    dt = float(np.median(np.diff(t)))
+    if not np.isfinite(dt) or dt <= 0:
+        return x, target_fs, None
+    fs = 1.0 / dt
+    if abs(fs - target_fs) / target_fs < 0.02:
+        return x, fs, None
+    n = int(round(len(x) * target_fs / fs))
+    if n < 8:
+        return x, fs, None
+    y = resample(x, n, axis=0).astype(np.float32)
+    return y, target_fs, n
+
+
+def robust_scale(x: np.ndarray) -> np.ndarray:
+    scale = np.median(np.abs(x), axis=0) / 0.6745
+    scale = np.asarray(scale, dtype=np.float32)
+    scale[scale < 1e-6] = 1.0
+    return scale
+
+
+def mains_ratio(x: np.ndarray, fs: float, mains: float = 50.0) -> np.ndarray:
+    """Fraction of 20-120 Hz power sitting in a 2 Hz band around mains. Per channel."""
+    n = x.shape[0]
+    if n < int(fs):
+        return np.full(x.shape[1], np.nan, dtype=np.float32)
+    spec = np.abs(np.fft.rfft(x, axis=0)) ** 2
+    freqs = np.fft.rfftfreq(n, d=1.0 / fs)
+    band = (freqs >= 20.0) & (freqs <= 120.0)
+    line = (freqs >= mains - 1.0) & (freqs <= mains + 1.0)
+    total = spec[band].sum(axis=0) + 1e-12
+    return (spec[line].sum(axis=0) / total).astype(np.float32)

aura_pipeline/split.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import numpy as np
+
+
+def assign_sessions(names: list[str], cfg: dict) -> dict[str, list[str]]:
+    """Assign each session file to train, validation, or test.
+
+    Windows from one file stay in one role. Adjacent windows overlap.
+    """
+    known = set(names)
+    pinned = {
+        "train": list(cfg.get("train_sessions") or []),
+        "val": list(cfg.get("val_sessions") or []),
+        "test": list(cfg.get("test_sessions") or []),
+    }
+    if any(pinned.values()):
+        missing = [n for group in pinned.values() for n in group if n not in known]
+        if missing:
+            raise SystemExit("Split lists name unknown sessions: " + ", ".join(missing))
+        used = [n for group in pinned.values() for n in group]
+        if len(used) != len(set(used)):
+            raise SystemExit("A session is listed in more than one of train, val, test.")
+        leftover = [n for n in names if n not in set(used)]
+        rng = np.random.default_rng(int(cfg.get("seed", 7)))
+        rng.shuffle(leftover)
+        if not pinned["test"]:
+            n_test = max(1, int(round(len(names) * float(cfg.get("test_fraction", 0.2)))))
+            pinned["test"] = leftover[:n_test]
+            leftover = leftover[n_test:]
+        if not pinned["val"]:
+            n_val = max(1, int(round(len(names) * float(cfg.get("val_fraction", 0.2)))))
+            pinned["val"] = leftover[:n_val]
+            leftover = leftover[n_val:]
+        pinned["train"] = pinned["train"] + leftover
+        if not pinned["train"] or not pinned["val"] or not pinned["test"]:
+            raise SystemExit("Split needs at least one train, one val, and one test session.")
+        return pinned
+
+    if len(names) < 3:
+        raise SystemExit(
+            f"Need at least 3 session files for train / val / test. Found {len(names)}. "
+            "Add recordings to data/raw."
+        )
+
+    order = list(names)
+    rng = np.random.default_rng(int(cfg.get("seed", 7)))
+    rng.shuffle(order)
+    n_test = max(1, int(round(len(order) * float(cfg.get("test_fraction", 0.2)))))
+    n_val = max(1, int(round(len(order) * float(cfg.get("val_fraction", 0.2)))))
+    if n_test + n_val >= len(order):
+        n_test, n_val = 1, 1
+    return {
+        "test": order[:n_test],
+        "val": order[n_test:n_test + n_val],
+        "train": order[n_test + n_val:],
+    }

config.yaml

@@ -0,0 +1,72 @@
+# Paths are relative to this directory.
+# Put session xlsx or csv files in data/raw, then run: python train.py
+
+data_dir: data/raw
+# Used only when data/raw has no session files.
+fallback_data_dir: ../dataset
+
+sample_rate_hz: 250
+window_sec: 1.0
+hop_sec: 0.1
+# Samples within this many seconds of a label change are unlabeled.
+edge_trim_sec: 0.2
+min_label_fraction: 0.9
+
+# ONNX output index 0 is rest. Do not reorder.
+classes:
+  - rest
+  - fist
+  - open
+  - pinch
+  - point
+  - thumb-up
+
+# 1-based channel numbers to force off, in addition to hard QC failures.
+drop_channels: []
+auto_drop_hard_failures: true
+# Zero a channel in the exported graph if it hard-fails in at least this fraction of train and validation files.
+global_drop_fraction: 0.5
+
+# Optical columns are last-value holds on the EMG clock. Left off unless that rate has been checked.
+drop_optical_disagreement: false
+optical_conf_min: 0.6
+
+# Causal filter applied before the network. Not baked into the ONNX graph.
+bandpass_hz: [20, 120]
+bandpass_order: 4
+notch_mains_hz: 50
+notch_harmonic_hz: 100
+notch_q: 30
+
+epochs: 40
+batch_size: 64
+lr: 0.001
+weight_decay: 0.0001
+patience: 8
+seed: 7
+
+# Split unit is the session file. Fractions apply only when the three lists are empty.
+# Paste names from runs/<timestamp>/split.json to freeze an assignment.
+# Unlisted files are appended to train.
+val_fraction: 0.2
+test_fraction: 0.2
+train_sessions: []
+val_sessions: []
+test_sessions: []
+loso: false
+
+# Continuous hand-pose regression (python train.py --pose). Parallel to the classifier.
+# Target is the optical hand tracker carried in the session file, not motion capture.
+# Each DoF is already scaled to [0, 1]; the model head is a sigmoid.
+pose_targets:
+  - thumb_curl
+  - index_curl
+  - middle_curl
+  - ring_curl
+  - pinky_curl
+  - pinch
+  - openness
+# Drop a window whose median optical confidence is below this.
+pose_min_conf: 0.3
+# SmoothL1 transition point, in target units.
+pose_loss_beta: 0.1

data/raw/README.md

@@ -0,0 +1,5 @@
+Session files for training. One file per recording. Not committed.
+
+Accepted: `.xlsx` (first sheet) and `.csv` with columns `t`, `ch1`..`ch8`, and `label`. Optional: `emg_new`, `label_source`, `optical_class`, `optical_conf`, `optical_present`.
+
+IMU columns are not used. Labeling, filtering, and the train/validation/test split are specified in the pipeline README.

infer.py

@@ -0,0 +1,63 @@
+"""Mock one live window. Filter and scale are the caller's job; they are not in the ONNX graph."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+import onnxruntime as ort
+
+from aura_pipeline.config import ROOT, load_config
+from aura_pipeline.signal import causal_filter, design_sos, robust_scale
+
+WIN = 250
+N_CH = 8
+WARMUP = 125  # 0.5 s at 250 Hz. Training drops this after the causal filter.
+
+
+def resolve_onnx(arg: str | None) -> Path:
+    if arg:
+        path = Path(arg)
+        return path.resolve() if path.is_absolute() else (Path.cwd() / path).resolve()
+    latest = ROOT / "runs" / "latest.txt"
+    if latest.is_file():
+        cand = Path(latest.read_text(encoding="utf-8").strip()) / "model.onnx"
+        if cand.is_file():
+            return cand
+    found = sorted((ROOT / "runs").glob("*/model.onnx"))
+    if found:
+        return found[-1]
+    raise SystemExit("No model.onnx. Train with python train.py, or pass a path.")
+
+
+def main() -> int:
+    cfg = load_config()
+    onnx_path = resolve_onnx(sys.argv[1] if len(sys.argv) > 1 else None)
+    if not onnx_path.is_file():
+        raise SystemExit(f"Missing {onnx_path}")
+    contract_path = onnx_path.parent / "contract.json"
+    contract = json.loads(contract_path.read_text(encoding="utf-8")) if contract_path.is_file() else {}
+    classes = list(contract.get("classes") or cfg["classes"])
+    input_name = str(contract.get("input_name") or "emg")
+    win = int(contract.get("window_samples") or WIN)
+
+    # Mock live EMG in microvolts, NTC (time, channel). Extra warmup matches training.
+    rng = np.random.default_rng(0)
+    raw = rng.normal(0, 25, size=(WARMUP + win, N_CH)).astype(np.float32)
+    filtered = causal_filter(raw, design_sos(float(cfg["sample_rate_hz"]), cfg))[WARMUP:]
+    window = (filtered / robust_scale(filtered)).astype(np.float32)[None, :, :]
+
+    sess = ort.InferenceSession(str(onnx_path), providers=["CPUExecutionProvider"])
+    probs = sess.run(None, {input_name: window})[0][0]
+    print(f"onnx {onnx_path}")
+    print(f"input {tuple(window.shape)} float32  time x channel  scaled EMG")
+    for name, p in zip(classes, probs):
+        print(f"  {name:10s} {float(p):.4f}")
+    print(f"sum {float(probs.sum()):.4f}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

notebooks/loso.ipynb

@@ -0,0 +1,152 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "b3f65536",
+   "metadata": {},
+   "source": [
+    "# LOSO (Kaggle or Colab GPU)\n",
+    "\n",
+    "`python train.py --loso`: one classifier train, then leave-one-session-out on train+val. Test files stay sealed.\n",
+    "\n",
+    "AuraNet is small. A free T4 is enough. CPU LOSO is hours; do not run it on a laptop as the default.\n",
+    "\n",
+    "1. Runtime / accelerator: GPU.\n",
+    "2. Do **not** `pip install torch`. The runtime already has CUDA PyTorch.\n",
+    "3. Put session `.xlsx` / `.csv` in `data/raw/` (~104 MB, not in git).\n",
+    "4. `loso.json` is written after each fold."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b601de9d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os, shutil, subprocess, sys\n",
+    "from pathlib import Path\n",
+    "\n",
+    "import torch\n",
+    "\n",
+    "print(\"cuda\", torch.cuda.is_available(), torch.cuda.get_device_name(0) if torch.cuda.is_available() else None)\n",
+    "if not torch.cuda.is_available():\n",
+    "    raise SystemExit(\"No GPU. Kaggle: Settings > Accelerator > GPU. Colab: Runtime > Change runtime type > T4 GPU.\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fdabba89",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Repo root: this notebook lives in notebooks/ when run from a clone.\n",
+    "root = Path.cwd()\n",
+    "if (root / \"notebooks\").is_dir() and (root / \"train.py\").is_file():\n",
+    "    pass\n",
+    "elif (root.parent / \"train.py\").is_file():\n",
+    "    os.chdir(root.parent)\n",
+    "elif (root / \"train.py\").is_file():\n",
+    "    pass\n",
+    "else:\n",
+    "    raise SystemExit(\"Run from the repo (folder that contains train.py), or cd there first.\")\n",
+    "print(\"cwd\", Path.cwd())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dbe77f48",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Install extras only. Skip torch.\n",
+    "subprocess.check_call([\n",
+    "    sys.executable, \"-m\", \"pip\", \"install\", \"-q\",\n",
+    "    \"numpy>=1.26\", \"pandas>=2.2\", \"openpyxl>=3.1\", \"scipy>=1.11\", \"PyYAML>=6.0\",\n",
+    "    \"onnx>=1.16\", \"onnxruntime>=1.18\",\n",
+    "])\n",
+    "print(\"ok\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b7bd15e2",
+   "metadata": {},
+   "source": [
+    "## Data\n",
+    "\n",
+    "Copy files into `data/raw/`.\n",
+    "\n",
+    "- Kaggle: add the session dataset, then set `SRC` to that input path.\n",
+    "- Colab: upload the xlsx files, or copy from Drive."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5392ee02",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "raw = Path(\"data/raw\")\n",
+    "raw.mkdir(parents=True, exist_ok=True)\n",
+    "\n",
+    "# Optional: copy from a Kaggle input or Drive folder.\n",
+    "SRC = os.environ.get(\"AURA_DATA\", \"\")  # e.g. /kaggle/input/your-dataset\n",
+    "if SRC:\n",
+    "    src = Path(SRC)\n",
+    "    n = 0\n",
+    "    for p in list(src.glob(\"*.xlsx\")) + list(src.glob(\"*.csv\")):\n",
+    "        dest = raw / p.name\n",
+    "        if not dest.exists():\n",
+    "            shutil.copy2(p, dest)\n",
+    "        n += 1\n",
+    "    print(\"copied\", n, \"from\", src)\n",
+    "\n",
+    "files = sorted(p.name for p in raw.iterdir() if p.suffix.lower() in {\".xlsx\", \".csv\"} and not p.name.startswith(\"~$\"))\n",
+    "print(len(files), \"session files\")\n",
+    "print(\"\\n\".join(files))\n",
+    "if len(files) < 3:\n",
+    "    raise SystemExit(\"Need at least 3 session files in data/raw/.\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6c426d06",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "subprocess.check_call([sys.executable, \"train.py\", \"--loso\"], cwd=str(Path.cwd()))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "52c39220",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "\n",
+    "latest = Path(\"runs/latest.txt\").read_text(encoding=\"utf-8\").strip()\n",
+    "path = Path(latest) / \"loso.json\"\n",
+    "print(path)\n",
+    "rows = json.loads(path.read_text(encoding=\"utf-8\"))\n",
+    "if isinstance(rows, dict) and \"scores\" in rows:\n",
+    "    rows = rows[\"scores\"]\n",
+    "for r in rows:\n",
+    "    print(f\"{r['session']:20s}  {100 * r['balanced_accuracy']:.1f}%\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

requirements.txt

@@ -0,0 +1,8 @@
+numpy>=1.26
+pandas>=2.2
+openpyxl>=3.1
+scipy>=1.11
+PyYAML>=6.0
+torch>=2.2
+onnx>=1.16
+onnxruntime>=1.18

train.py

@@ -0,0 +1,6 @@
+"""Train from this folder: python train.py"""
+
+from aura_pipeline.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())