emg2mu: GPU-Accelerated High-Density EMG Decomposition

A PyTorch-accelerated toolkit for decomposing high-density EMG (hdEMG) signals into individual motor unit action potentials using blind source separation techniques.

Features

• Fast motor unit decomposition using GPU-accelerated Independent Component Analysis (ICA)
• Efficient signal preprocessing including whitening and noise injection
• Automated duplicate motor unit removal
• Quality assessment using silhouette coefficients
• Interactive visualization of decomposed spike trains
• Compatible with common hdEMG datasets (e.g., Hyser dataset)

Installation

# Download the repository from GitHub
git clone https://github.com/neuromechanist/emg2mu

# Install the package
cd emg2mu
pip install .

# For development installation with testing dependencies
pip install -e ".[test]"

Testing

The package includes a comprehensive test suite. To run the tests:

# Run all tests
pytest

# Run tests with coverage report
pytest --cov=emg2mu

# Run tests in parallel
pytest -n auto

# Run specific test file
pytest emg2mu/tests/test_decomposition.py

The test suite includes:

• Unit tests for core functionality
• Integration tests for the complete workflow
• Device-specific tests for GPU acceleration
• Synthetic data generation for reproducible testing

All tests use synthetic data generated within the test suite, making them fast and resource-efficient to run.

Quick Start

from emg2mu import EMG

# Load and decompose hdEMG data
emg = EMG('path/to/data.mat')
emg.preprocess()
emg.run_ica(method='torch')  # Uses GPU acceleration
emg.remove_duplicates()
emg.compute_scores()
emg.plot(plot_type='spike_train', min_score=0.93)
emg.plot(plot_type='waveforms', min_score=0.93)
emg.save('path/to/save')

Sample Dataset

The package includes a sample dataset in the sample_data folder. You can pass the sample file ('emg2mu/sample_data/sample1.mat') to get the plots below:

Unfortunately, the sample ICA decomposition is not included due to the file size limitation. However, using the PyTorch-accelerated ICA algorithm, you can decompose the sample data in a couple of minutes.

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

References

When using this toolbox, please cite:

@software{shirazi2024emg2mu,
  author = {Shirazi, Seyed Yahya},
  title = {emg2mu: GPU-accelerated High-Density EMG Decomposition},
  year = {2024},
  publisher = {GitHub},
  url = {https://github.com/neuromechanist/emg2mu}
}

License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License - see the LICENSE file for details.

Acknowledgments

This toolbox is based on the hdEMG decomposition toolbox in Matlab and introduces a Pythonic implementation of the algorithm with the GPU-accelerated FastICA algorithm and vectorized silhouette scoring algorithm.

Note: The motor-unit scoring mechanism uses a different algorithm than the one used in the Matlab counterpart, resulting in overall higher scores for similar decompositions. However, I believe that this one is more transparent, scalable, and extensible. Please keep in mind the change.

Contact

Seyed (Yahya) Shirazi - @neuromechanist

Project Link: https://github.com/neuromechanist/emg2mu