muniverse-emg 0.1.4

A modular framework for simulated and experimental EMG dataset generation, motor unit decomposition algorithm benchmarking, and performance evaluation

MUniverse: Benchmarking Motor Unit Decomposition Algorithms

MUniverse is a modular framework for simulated and experimental EMG dataset generation, motor unit decomposition algorithm benchmarking, and performance evaluation. It integrates biomechanical simulation (via NeuroMotion), generative models (BioMime), standardized formats (e.g. BIDS/Croissant), and FAIR data hosting (Harvard Dataverse).

Features

• 🔬 Algorithm Benchmarking: Compare multiple motor unit decomposition algorithms (CBSS, SCD, Upperbound, AE)
• 📊 Dataset Generation: Generate simulated EMG datasets using NeuroMotion and experimental datasets
• 📁 FAIR Data: Access datasets through Harvard Dataverse with BIDS and Croissant format support
• 🔧 Containerized Workflows: Docker and Singularity support for reproducible algorithm execution
• 📈 Performance Evaluation: Comprehensive evaluation metrics and report card generation
• 📓 Tutorial Notebooks: Interactive Jupyter notebooks for dataset loading and algorithm usage

Installation

Requirements

• Python 3.11 or higher
• pip

Package Installation

MUniverse is distributed as a Python package. To set up the development environment:

1. Clone the repository:

git clone https://github.com/dfarinagroup/muniverse.git
cd muniverse

2. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install the package:

# Install core dependencies
pip install -e .

# Install development dependencies (optional)
pip install -e ".[dev]"

Docker/Singularity Containers

For algorithm execution, Docker or Singularity containers are available. See the docker/ directory for container definitions.

Quick Start

Loading a Dataset

from muniverse.datasets import load_dataset

# Load a dataset from Harvard Dataverse
dataset = load_dataset("neuromotion-test", output_dir="./data")

Running Decomposition

from muniverse.algorithms import decompose_recording

# Run decomposition using CBSS algorithm
results, metadata = decompose_recording(
    data="path/to/emg_data.edf",
    method="cbss"
)

# Or use SCD algorithm (requires container)
results, metadata = decompose_recording(
    data="path/to/emg_data.edf",
    method="scd",
    container="path/to/muniverse_scd.sif",
    engine="singularity"
)

Available Datasets

All datasets are hosted on Harvard Dataverse and follow FAIR principles:

• Caillet et al. 2023 - DOI: 10.7910/DVN/F9GWIW
• Avrillon et al. 2024 - DOI: 10.7910/DVN/L9OQY7
• Grison et al. 2025 - DOI: 10.7910/DVN/ID1WNQ
• Neuromotion-Train - DOI: 10.7910/DVN/2UQHTP
• Neuromotion-Test - DOI: 10.7910/DVN/QYI336
• Hybrid-Tibialis - DOI: 10.7910/DVN/YHTGGA

Supported Algorithms

• CBSS - Convolutional Blind Source Separation
• SCD - Swarm Contrastive Decomposition (GitHub)
• Upperbound - Upper bound performance estimation
• AE - Autoencoder-based decomposition

Documentation (coming soon 🚧)

• 📖 GitHub Pages Site - Project documentation and overview
• 📓 Tutorial Notebooks - Interactive examples and guides
• 💻 Source Code - Repository and issue tracking
• 📊 Harvard Dataverse - Dataset access and metadata

Project Structure

muniverse/
├── src/                    # Package source code
│   └── muniverse/
│       ├── configs/        # Algorithm and dataset configurations
│       ├── datasets/       # Dataset loading and simulation utilities
│       ├── algorithms/     # Decomposition algorithms
│       ├── evaluation/     # Performance evaluation
│       └── utils/          # Utility functions
├── notebooks/              # Tutorial notebooks
├── scripts/                # Utility scripts
├── docker/                 # Docker container definitions
├── docs/                   # GitHub Pages documentation (Coming soon!)
├── tests/                  # Unit tests
├── pyproject.toml          # Package configuration
└── README.md               

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

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

Contributors

• Pranav Mamidanna, 📧
• Thomas Klotz, 📧
• Dimitrios Halatsis
• Irene Mendez Guerra

Acknowledgments

• NeuroMotion - Biomechanical simulation framework (GitHub)
• Swarm-Contrastive-Decomposition - Decomposition algorithm (GitHub)
• Harvard Dataverse - FAIR data hosting platform
• BIDS - Brain Imaging Data Structure standard

Citation

If you use MUniverse in your research, please cite:

@inproceedings{NEURIPS2025_dcce2899,
 author = {Mamidanna, Pranav and Klotz, Thomas and Chalatsis, Dimitrios and Grison, Agnese and Mendez Guerra, Irene and Ma, Shihan and Caillet, Arnault and Avrillon, Simon and Rohl\'{e}n, Robin and Farina, Dario},
 booktitle = {Advances in Neural Information Processing Systems},
 editor = {D. Belgrave and C. Zhang and H. Lin and R. Pascanu and P. Koniusz and M. Ghassemi and N. Chen},
 pages = {},
 publisher = {Curran Associates, Inc.},
 title = {MUniverse: A Simulation and Benchmarking Suite for Motor Unit Decomposition},
 url = {https://proceedings.neurips.cc/paper_files/paper/2025/file/dcce28990bf662c6b916c52cd7e975da-Paper-Datasets_and_Benchmarks_Track.pdf},
 volume = {38},
 year = {2025}
}

Contact

For questions, issues, or contributions, please:

• Open an issue on GitHub
• Contact the maintainers via email (see the Contributors section for author emails)

License

MUniverse is licensed under the GNU General Public License v3.0 (GPL-3.0).

Important Licensing Notes:

• This project uses NeuroMotion, which is licensed under GNU GPL v3.0. As a result, MUniverse is also licensed under GNU GPL v3.0 to comply with the copyleft requirements of the GPL license.
• This project also integrates with Swarm-Contrastive-Decomposition, which is licensed under Creative Commons Attribution-NonCommercial 4.0 International Public License.

See the LICENSE file for full details.