Curated Residual Decomposition - Help Tool

A self-contained Python GUI for the computation of the residual signal from a HD-EMG decomposition file for application of the Curated Residual Decomposition approach. The tool includes two steps:

1. Computing and saving the residual EMG after a decomposition for subsequent decomposition
2. Combining the decomposed & cleaned residual decomposition with the original (or previous) decomposition

The tool currently supports file formats corresponding to the DEMUSE or MUedit decomposition implementations. Files formatted in alternative ways need to be converted to one of the two types first.

Dependencies: NumPy, SciPy, PyQt6 and h5py (h5py is required to read MATLAB v7.3 / HDF5 MUedit files).

Matlab version:

Folder matlab-version contains a functionally identical version in MATLAB, including the GUI. Run ResidualEMGTool in the command window with the folder in the path or current working directory.

Dependencies: Matlab 2021b or newer, Signal Processing toolbox.

If you use this tool in academic work, please cite: Osswald, M., Del Vecchio, A., Curated Residual Decomposition for Increased MU Yield from HD-sEMG, bioRxiv (2026).

Install & run

Quick start (no install):

pip install -r requirements.txt
python main.py

Or install as a package (provides the residual-emg-tool command):

pip install -e .
residual-emg-tool          # or:  python -m residual_tool

Workflow

1. Decompose and clean the original recording.
2. Use this tool to load the cleaned decomposition and Compute and save Residuals.
3. Decompose and clean the saved residual signal file.
4. Use this tool to Combine the cleaned residual decomposition with the original decomposition.

Features

• File format selector — DEMUSE or MUedit. The whole pipeline reads and writes files in the selected convention.
• Load decomposition — loads a cleaned, decomposed .mat file.
• STA window — full window for MUAP template estimation.
• Compute and save Residuals — peel-off (spike-triggered averaging + template subtraction), then save the residual in place of the original signal, ready to re-decompose.
• Combine — cross-correlation matching of spike trains to add only the unique new MUs from the re-decomposed residual to the original file. Duplicate-detection parameters (xcorr threshold 0.20, window ±200 ms) are fixed in code for consistency, not exposed in the UI.
• Help — a button opens a window with methodological documentation.

Module layout

Module	Responsibility
residual_tool/peel_off.py	STA + in-place template subtraction (pure NumPy)
residual_tool/matio.py	.mat loading + DEMUSE-format helpers
residual_tool/residuals.py	residual computation + redecompose-file assembly
residual_tool/combine.py	spike-train xcorr matching + combined-file assembly
residual_tool/muedit.py	MUedit-format read/residual/combine (v7 + v7.3)
residual_tool/gui.py	PyQt6 main window
residual_tool/help_text.py	HTML help content for the Help window
main.py	entry point

DEMUSE file variables

• SIG — H×W cell array of monopolar EMG time series (column-major).
• MUPulses — 1×N_MU cell array of 1-based discharge sample indices.
• fsamp — sampling frequency (Hz).
• discardChannelsVec — binary mask of excluded channels.
• PNR — optional quality metric (carried through in the combined file).
• IPTs — optional pulse trains (carried through in the combined file).

MUedit file variables

A MUedit .mat contains a signal struct (and, for edited files, edition and parameters). Read/written fields:

• signal.data — [n_channels × n_samples] (grids concatenated row-wise).
• signal.fsamp, signal.ngrid, signal.nChan, signal.gridname, signal.muscle, signal.target, signal.path.
• signal.EMGmask — per-grid masks; their lengths split data into grids.
• edition.Pulsetrain{g} / edition.Dischargetimes{g,m} — cleaned MUs (1-based discharge indices). Required: a file without an edition struct has not been manually edited and is rejected with an error.

v7 files are read with scipy; v7.3 (HDF5) files via h5py. Output files are written as MATLAB v5 (scipy), which MUedit loads without issue. The residual output is an import-format signal struct (MU fields removed); the combined output stores merged MUs in signal.Pulsetrain/Dischargetimes with no edition struct (save it under a name without "edited").

Note: MUedit v7.3/HDF5 files are read by dereferencing HDF5 cell arrays. The single-grid path has been exercised on real files; for multi-grid files, check the per-grid MU counts reported on load before relying on the output.

License

Copyright © 2026 Marius Osswald, n-squared Lab, FAU Erlangen-Nürnberg.

Released under the GNU General Public License v3.0 — see LICENSE. You may use, modify and redistribute this software under the terms of the GPL; distributed derivatives must also be licensed under the GPL and provide source.